@ngocsangairvds/vsaf 4.0.6 → 4.0.8

package/skills/vds-skill/vds-scripts/docker/ADR.md

@@ -0,0 +1,392 @@
+# VDS Infrastructure ADRs — Operator Routing Manifest
+
+> **Spec authoritative**. The canonical decision text for each ADR-INF-N lives at:
+> `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §7 ADRs.
+>
+> This file is a tiered routing manifest:
+> - **INF-1..7**: 3-6 line operator-facing pointer + spec link (no restated content).
+> - **INF-8..12**: pointer + extended operator content (postmortems, regression tests,
+>   downgrade pattern, REDIS DB supersession, Tier 3 sub-shape table) that is
+>   directly load-bearing during incident response. The size budget reflects this
+>   intentional inline-when-load-bearing policy rather than full mirroring.
+>
+> Last sync: master@5f0c97b4 (post-v2.15.17, 2026-04-28).
+
+## ADR-INF-1 — Schema-per-Domain over Database-per-Service
+
+**Status**: Accepted (P0) | **Spec**: `design.md` §ADR-INF-1
+
+Single shared Postgres instance with per-service schema isolation (`audit_state`, `memory`, `sched`, `progress`, `dbos`). Each service gets a dedicated schema + role. Simpler to operate than 5 separate database instances.
+
+→ Full rationale, consequences, rejected alternatives: `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §ADR-INF-1
+
+## ADR-INF-2 — Redis Logical DB over Multiple Redis Instances
+
+**Status**: Accepted (P0) | **Spec**: `design.md` §ADR-INF-2
+
+Single Redis instance with logical DB separation (DBs 0–9). Each consumer gets a dedicated DB number. Redis natively supports 16 logical databases; one instance is simpler to operate.
+
+→ Full rationale, consequences, rejected alternatives: `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §ADR-INF-2
+
+## ADR-INF-3 — Profile-Based Compose over Directory-Per-Service
+
+**Status**: Accepted (P0) | **Spec**: `design.md` §ADR-INF-3
+
+Docker Compose profiles (`--profile <name>`) for selective service activation instead of per-service compose directories. Standard Docker Compose mechanism; operators learn profile names instead of navigating directory trees.
+
+→ Full rationale, consequences, rejected alternatives: `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §ADR-INF-3
+
+## ADR-INF-4 — Host-Only Policy for vds-skills and git
+
+**Status**: Accepted (P0) | **Spec**: `design.md` §ADR-INF-4
+
+Skills sync, memory operations, and git operations run on host only — never in containers. These interact with iCloud-synced paths, SSH keys, and git state that don't map cleanly into container filesystems.
+
+→ Full rationale, consequences, rejected alternatives: `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §ADR-INF-4
+
+## ADR-INF-5 — Qdrant Instance Separation
+
+**Status**: Accepted (P0) | **Spec**: `design.md` §ADR-INF-5
+
+Separate Qdrant instances for grepai (ports 6333/6334) and VDS memory (ports 6335/6336). Different version requirements and collection schemas; port offset avoids collision.
+
+→ Full rationale, consequences, rejected alternatives: `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §ADR-INF-5
+
+## ADR-INF-6 — Celery Broker DB Explicit Assignment
+
+**Status**: Accepted (P0) | **Spec**: `design.md` §ADR-INF-6
+
+Celery broker explicitly assigned to Redis DB 0 via `CELERY_BROKER_URL` with `/0` suffix. Prevents accidental DB collision when multiple Redis consumers are added.
+
+→ Full rationale, consequences, rejected alternatives: `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §ADR-INF-6
+
+## ADR-INF-7 — Compose Project Identity Anchor
+
+**Status**: Accepted (P2) | **Spec**: `design.md` §ADR-INF-7
+
+All three compose files declare `name: vds-platform`. CLI invocations use `-p vds-platform` for defense in depth. Ensures containers, networks, and volumes belong to one Compose project regardless of which `-f` flags are passed or which directory the command runs from.
+
+→ Full rationale, consequences, rejected alternatives: `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §ADR-INF-7
+
+## ADR-INF-8 — `python3` for stdlib-only verification (not `vds-cli`/`uv`)
+
+**Status**: Accepted (v2.8.0 — operator-facing verification path stabilized)
+
+**Date**: 2026-04-25 | **Spec**: `design.md` §ADR-INF-8
+
+### Decision
+
+`scripts/verify-infra-topology.py` is invoked as bare `python3 scripts/verify-infra-topology.py` from the Makefile, the `infrastructure-evolution-skill/scripts/verify.sh` wrapper, and the operator docs. It is NOT routed through `vds-cli` and is NOT wrapped in `uv run --project vds_cli`.
+
+### Rationale
+
+- The script imports only Python stdlib (`argparse`, `json`, `subprocess`, `sys`, `dataclasses`, `typing`) — zero third-party deps.
+- `uv run` adds 60-650ms cold-start overhead per invocation; `uv run --project` additionally couples the script to a workspace lockfile that can drift, breaking the verify path during incident response (the exact moment we need it most).
+- `vds-cli` is reserved for orchestrator commands that need project deps; pulling stdlib utilities into the router dilutes that boundary.
+- Using `python3` (not bare `python`) avoids the macOS / minimal-Linux ambiguity where `python` may point at python2 or be absent.
+- Aligns with VDS rule `feedback_hooks_no_uv_for_stdlib.md` (stdlib hooks use `python3`, not `uv run`).
+
+### Consequences
+
+- The script is callable from any environment with a Python 3.10+ interpreter — including broken venvs and bare hosts during cutover or post-incident recovery.
+- Trade-off: loss of `vds-cli --help` central discovery for the verify command; compensated by `make verify` (Makefile target) and the skill wrapper `infrastructure-evolution-skill/scripts/verify.sh`.
+- New stdlib-only verification scripts in this repo SHOULD follow the same `python3 scripts/<name>.py` invocation pattern.
+
+## ADR-INF-9 — Resolve Redis DB 6 double-booking: tool discovery moves to DB 9
+
+**Status**: Accepted (v2.4.0 — supersedes the DB 6 assignment in ADR-INF-6)
+
+**Date**: 2026-04-25 | **Spec**: `design.md` §ADR-INF-9
+
+### Decision
+
+`memory_orchestrator`'s `REDIS_TOOL_DISCOVERY_DB` defaults to **9** (not 6). DB 6 is reserved exclusively for `multi_agent_orchestrator` agent state. The "9+ reserved for future services" range is now formally allocated starting at 9.
+
+### Rationale
+
+- ADR-INF-6 reassigned `redis_tool_discovery_db` from DB 0 (Celery collision) to DB 6 to satisfy `requirements.md`'s "must be reassigned to DB 5 or higher".
+- That wording was satisfied but landed on the DB this design assigned to multi-agent agent state, recreating exactly the silent-collision risk ADR-INF-6 was meant to eliminate.
+- Without explicit key-prefix isolation guarantees, dual-tenancy in DB 6 is unsafe for two unrelated services.
+- DB 9 is the next free slot per the FR-3 allocation table; tool discovery is "not yet wired" in production, so no data migration is required.
+
+### Consequences
+
+- One-line compose env change: `REDIS_TOOL_DISCOVERY_DB: ${REDIS_TOOL_DISCOVERY_DB:-9}`.
+- One-line `memory_orchestrator/src/.../config.py` field default change.
+- FR-3 design table extended to formally include DB 9.
+- ADR-INF-6 remains historically accurate (it documents the DB 0 → DB 6 move); this ADR supersedes only the destination.
+
+## ADR-INF-10 — Service vs CLI Container Patterns
+
+**Status**: Accepted (v2.8.0 — Tier-2 split codified during three-tier compose rollout)
+
+**Date**: 2026-04-25 | **Spec**: `design.md` §ADR-INF-10
+
+### Decision
+
+Tier-2 compose entries split into two patterns based on whether the orchestrator's runtime is a daemon or a one-shot command:
+
+| Pattern | Examples | `restart` | HEALTHCHECK | Operational invocation |
+|---|---|---|---|---|
+| **Long-running service** | memory-api, memory-worker, scheduler, multi-agent | `unless-stopped` | HTTP/port probe | `up -d` → `docker ps` shows `Up X minutes (healthy)` |
+| **On-demand CLI** | audit, pdf, progress, db-query | `"no"` | none | `docker compose -p vds-platform run --rm <service> <subcommand>` |
+
+### Rationale
+
+- Earlier rollout iterations applied `restart: unless-stopped` uniformly to all Tier-2 entries; this caused audit/pdf/progress/db-query to perpetually restart-loop after each clean exit (CLI runs `--help`, exits 0, daemon restarts it, repeat).
+- The fix is NOT to grow a `serve` mode for each CLI — that is feature work, not infra plumbing.
+- Instead, acknowledge that the FR-4 services divide into two patterns and configure each correctly at the compose layer.
+
+### Consequences
+
+- A healthy `vds-platform` project's `docker ps` shows 4 long-running services + 4 exited CLI containers. The `Exited (0)` state is **normal**, not a failure signal.
+- Operators MUST invoke CLI containers via `docker compose -p vds-platform run --rm <service> <subcommand>` rather than `up -d`. Documented in `MIGRATION.md` and `infrastructure-evolution-skill`.
+- If audit or pdf grow a daemon mode in the future (e.g., a job-queue dispatcher), reclassifying them is a one-line compose change (`restart: "no"` → `restart: unless-stopped`) plus a CMD update.
+- `verify-infra-topology.py` profile checks treat CLI profiles (progress, db-query, audit-when-CLI, pdf-when-CLI) as "infra-only expected running" — only the shared infra needs to be up; the CLI profile's container exiting is expected.
+
+#### Tier 3 Sub-Shapes (simplified v2.15.10)
+
+Only **3A — Operator-CLI** remains active. Operators invoke CLI containers via
+`docker compose run --rm <service> <subcommand>` (or `make run-<service> ARGS=...`).
+
+| Sub-shape | Invoked by | Examples | Where |
+|---|---|---|---|
+| **3A — Operator-CLI** | Human operator | `audit`, `pdf`, `progress`, `db-query`, `vds-cli`, `mcp-server` | `docker-compose.cli.yml` |
+| **3B — Auto-init one-shot** | *(retired v2.15.10)* | — | — |
+
+Pre-v2.15.10, `memory-migrate` was a Tier 3B auto-init container that ran
+`alembic upgrade head` before the main service started. The entire sub-shape
+was retired when ADR-INF-10 adopted the single-tier deploy model: each
+long-running service's entrypoint runs alembic before exec'ing uvicorn,
+eliminating cross-file `depends_on` and the two-tier privilege model.
+
+`make up-<service>` loads only `docker-compose.services.yml`. The CLI file
+(`docker-compose.cli.yml`) is loaded only for explicit operator-CLI invocations
+(`make run-audit`, etc.).
+
+
+## ADR-INF-11 — Alembic Migration Standard
+
+**Status**: Accepted (P4 v2.11.1; simplified P5 WP-5.1 at `c1a3585d`)
+
+**Date**: 2026-04-25 (P4); 2026-04-26 (P5 WP-5.1 simplification) | **Spec**: `design.md` §ADR-INF-11
+
+### Decision
+
+All DB-backed VDS orchestrators MUST use Alembic for schema migrations. Each
+service owns its own `alembic.ini` + `alembic/env.py` + `alembic/versions/`
+tree. There is **no** monorepo-wide single Alembic environment. Schema/role
+bootstrap (one-time at postgres container init) lives in
+`docker/infrastructure/init-schemas.sql`; per-service table CREATE/ALTER
+ownership belongs to that service's Alembic env.
+
+Services in scope (post P5 WP-5.1):
+
+| Service | Alembic env | Version table |
+|---|---|---|
+| memory_orchestrator | `memory_orchestrator/alembic/` | `memory.alembic_version` |
+| audit_orchestrator | `audit_orchestrator/alembic/` | `audit_state.alembic_version` |
+| progress_report_orchestrator | `progress_report_orchestrator/alembic/` | `progress.alembic_version` |
+| scheduler_orchestrator | `scheduler_orchestrator/alembic/` | `sched.alembic_version` |
+
+**Rule for new services**: always use `version_table_schema="<service-schema>"` in env.py
+(in-schema is the single policy; the former scheduler-in-public exception was a doc
+artifact — `c1a3585d` removed it).
+
+### Rationale
+
+1. **Industry-standard for FastAPI + SQLAlchemy 2.0 + Postgres (2026)** — same operational vocabulary as the broader Python ecosystem.
+2. **Already proven on master** — memory phase197 (`f4c91c8d`) and scheduler (pre-spec); P4 extends to audit + progress.
+3. **Autogenerate prevents missing-table bugs** — phase196 found 4 ORM tables with no matching migration, causing prod 500s; `alembic revision --autogenerate` would have caught these at PR time.
+4. **`op.execute()` retains raw-SQL flexibility** for pgvector HNSW, GIN expression indexes, views, complex CHECK constraints.
+5. **Per-service ownership** matches ADR-INF-1 (schema-per-domain); each env owns ONLY its own schema.
+6. **No JVM/Go runtime added** (vs Flyway, Atlas, golang-migrate) — Alembic is Python-native, ships in `pip`.
+
+### Canonical env.py pattern (6 design choices)
+
+```python
+# (1) include_name imported from a sibling module — NOT inline in env.py
+from vds_<service>_orchestrator.db.alembic_filters import include_name
+from vds_<service>_orchestrator.service.models.database import Base
+
+target_metadata = Base.metadata  # (3) for autogenerate
+
+context.configure(
+    connection=connection,
+    target_metadata=target_metadata,
+    include_name=include_name,                  # (1) schema filter
+    include_schemas=True,                       # (2) cross-schema awareness
+    version_table_schema="<service-schema>",    # (4) in-schema policy (ADR-INF-11)
+    # (5) DSN from DATABASE_URL env var (set by <svc>-migrate compose service);
+    #     strip `?options=...` before passing to asyncpg engine.
+    # (6) search_path via DSN options + DB-level ALTER — NEVER inline SET.
+)
+```
+
+### `version_table_schema` Policy (simplified at P5 WP-5.1 / `c1a3585d`)
+
+All services use in-schema placement: `memory.alembic_version`, `audit_state.alembic_version`,
+`progress.alembic_version`, `sched.alembic_version`. The earlier "scheduler in-public exception"
+was a doc artifact — scheduler's DSN `search_path=sched,public` causes Alembic's unqualified
+`CREATE TABLE alembic_version` to land in `sched` regardless; the prior ADR-INF-11 §Dual Policy
+table was stale. Live-state verification at `c1a3585d` confirmed all 4 services are in-schema.
+
+**Rule for new services**: always use `version_table_schema="<service-schema>"` in env.py.
+
+### SA2.0 Implicit-TX Gotcha (postmortem from `566217e5`, 2026-04-25)
+
+**Symptom**: `alembic_version` table never persisted; `alembic current` returned empty; every migrate run re-applied all migrations (idempotent so harmless, but operationally confusing).
+
+**Root cause**: `run_migrations_online()` contained `connection.execute(text("SET search_path TO memory, public"))` BEFORE `context.configure()`. Under SQLAlchemy 2.0+, this opens an *implicit transaction* that doesn't auto-commit before Alembic begins its own version-table tx, wrapping the version-table CREATE/INSERT in a phantom rollback path.
+
+**Fix**: removed the explicit `SET search_path` connection statement. The DSN already carries `?options=-c search_path=<schema>,public` and `ALTER DATABASE vds_platform SET search_path TO <schema>, public` is set as DB default — both work without opening an in-tx SET.
+
+**Rule**: NEVER call `connection.execute(text("SET ..."))` inside `run_migrations_online()` before `context.configure()`. Use DSN options + DB-level ALTER for search_path setup.
+
+### Search-Path Policy (WP-4.3)
+
+Every DSN for pgvector-using services MUST include `public` in search_path so the `vector_l2_ops` HNSW operator class is visible. Without it, migration 0003 (memory) failed with `operator class "vector_l2_ops" does not exist for access method "hnsw"`.
+
+Pattern (URL-encoded): `?options=-c%20search_path%3D<schema>%2Cpublic`. Optionally also: `ALTER DATABASE vds_platform SET search_path TO <schema>, public` for the DB-level default.
+
+### `init-schemas.sql` Ownership Boundary (WP-4.4)
+
+`docker/infrastructure/init-schemas.sql` runs ONCE at postgres container init. It owns **schemas + roles + DBOS CREATE grant ONLY** — never tables. Tables are owned by per-service Alembic envs. This separation guarantees a clean rollback path: dropping a schema doesn't strand orphan migration state in another service's `alembic_version` table.
+
+### `include_name` Location Standard (WP-4.8)
+
+**Canonical**: imported from `<service>/db/alembic_filters.py` module. Rationale: testable in isolation; reusable across online + offline `configure()` blocks; cleaner separation of filter logic from env wiring.
+
+Inline-in-env.py (legacy phase197 pattern in memory) was migrated to the canonical module in WP-4.8.
+
+### Compose-service pattern (HISTORICAL — retired v2.15.10 / ADR-INF-10)
+
+> ⚠️ **RETIRED in v2.15.10.** Migrations are now an explicit operator step:
+> `docker compose run --rm --no-deps --entrypoint /opt/venv/bin/alembic <service> -c <path>/alembic.ini upgrade head`.
+> The `<service>-migrate` auto-init container pattern below is historical
+> only. Post-P8 DSNs route through PgBouncer (e.g., `@vds-pgbouncer:6432/vds_memory`),
+> not `postgres:5432` with `?options=search_path`.
+
+```yaml
+# ⚠️ HISTORICAL — do not use
+<service>-migrate:
+  profiles: ["<service>", "full"]
+  build: { context: ../, dockerfile: <service>_orchestrator/Dockerfile }
+  image: vds-<service>:${VERSION:-1.0.0}
+  container_name: vds-<service>-migrate
+  depends_on: { postgres: { condition: service_healthy } }
+  environment:
+    DATABASE_URL: postgresql://postgres:${VDS_POSTGRES_PASSWORD}@postgres:5432/vds_platform?options=-c%20search_path%3D<schema>%2Cpublic
+  restart: "no"
+  command: [/opt/venv/bin/alembic, -c, /app/<service>_orchestrator/alembic.ini, upgrade, head]
+
+# ⚠️ HISTORICAL — do not use
+<service>-orchestrator:
+  depends_on:
+    <service>-migrate: { condition: service_completed_successfully }
+```
+
+### Schema-Drop-Safe Downgrade Pattern (P5 WP-5.1)
+
+**Problem**: A `0001` migration that creates a service-owned schema and whose original
+`downgrade()` does `DROP SCHEMA <schema> CASCADE` will wipe `<schema>.alembic_version`
+mid-transaction. Alembic deletes the version row AFTER running `downgrade()` — if the
+version table is gone, that step fails and the downgrade aborts with inconsistent state.
+
+**Concrete instance**: `scheduler_orchestrator/alembic/versions/0001_create_sched_schema.py`.
+Live `sched.alembic_version` lands in `sched` (in-schema policy above). Running
+`alembic downgrade base` with the original `DROP SCHEMA sched CASCADE` would abort.
+
+**Canonical fix** (P5 WP-5.1): make `0001.downgrade()` an intentional no-op:
+
+```python
+def downgrade() -> None:
+    """Intentional no-op. Do NOT DROP SCHEMA <schema> CASCADE here.
+
+    alembic_version lives in this schema; alembic deletes the version row
+    AFTER running downgrade(), so any DROP TABLE/SCHEMA here would cause
+    that deletion to fail. Operators wanting full schema teardown must run:
+        DROP SCHEMA sched CASCADE;
+    manually OUTSIDE alembic, then re-init with: alembic upgrade head.
+
+    By the time alembic reaches 0001.downgrade(), all >=0002 revisions have
+    already dropped their own domain tables via their own downgrade() methods.
+    """
+    # Nothing to drop here — alembic manages <schema>.alembic_version itself.
+```
+
+**Post-downgrade state**: `sched` schema persists holding only the now-empty
+`alembic_version` table (zero rows). This is intentional — alembic deleted the
+version row as part of its own internal cleanup. Full schema teardown is a manual
+operator step outside alembic.
+
+**Regression test**: `scheduler_orchestrator/tests/test_alembic_downgrade.py` — runs
+`upgrade head` → `downgrade base` → `upgrade head` cycle via testcontainers and
+asserts `sched.alembic_version` is populated/empty/repopulated at each phase.
+
+**References**: spec design.md §ADR-INF-11 §Schema-Drop-Safe Downgrade Pattern;
+TSK-5.1.1..TSK-5.1.7.
+
+### Idempotence Requirement
+
+Initial squash migrations subsuming pre-Alembic raw SQL (e.g., audit's WP-4.1, progress's WP-4.7) MUST use idempotence guards (`CREATE TABLE IF NOT EXISTS`, `DO $$ BEGIN ... EXCEPTION WHEN duplicate_object THEN NULL; END $$`).
+
+Cutover sequence: `alembic stamp 0001` (mark live schema as already-at-revision-N without re-running DDL) → subsequent `alembic upgrade head` is a no-op.
+
+### Consequences
+
+- Audit's 10+ phase-numbered raw SQL files retired to `audit_orchestrator/legacy/migrations/` with a README pointing at the squash migration.
+- Audit's `state/store.py:BOOTSTRAP_SQL` (~2500 LOC inline) deleted.
+- Audit's `init_schema()` stubbed to `RuntimeError`; production callers swapped to programmatic `alembic upgrade head`.
+- Audit's `_run_with_schema_autorepair()` deleted (drift-recovery wrapper now unnecessary by construction).
+- Progress's inline `_TABLES` dict + `init_schema()` deleted; CLI startup no longer auto-bootstraps.
+~~- New `audit-migrate` and `progress-migrate` Tier-3 CLI compose services (one-shot `alembic upgrade head`, downstream services use `depends_on: { condition: service_completed_successfully }`).~~|
+- Migrations run as explicit operator steps (`docker compose run --rm --no-deps <service> --entrypoint /opt/venv/bin/alembic <service> -c <path>/alembic.ini upgrade head`) — no auto-init one-shot services. (v2.15.10 / ADR-INF-10)
+- `verify-infra-topology.py` extension (WP-4.6) checks `<schema>.alembic_version` per managed schema.
+
+### Rejected alternatives
+
+- **Flyway / Atlas / golang-migrate** — JVM/Go runtime overhead for no Python-native gain.
+- **yoyo-migrations** — smaller community, no autogenerate.
+- **Hand-rolled `run_migrations.py`** — phase196 demonstrated the failure mode (4 missing tables undetected until prod 500s); 440-LOC tech debt rejected by phase197.
+- **Single monorepo Alembic env** — breaks ADR-INF-1 schema-per-domain ownership; forces cross-service coordination on every migration.
+
+### References
+
+- Alembic tutorial: https://alembic.sqlalchemy.org/en/latest/tutorial.html
+- Reference impl: `memory_orchestrator/alembic/env.py` (phase197 / `f4c91c8d` + `566217e5`)
+- Sibling reference: `scheduler_orchestrator/alembic/env.py` (pre-spec; now in-schema per c1a3585d)
+- Historical compose pattern (retired v2.15.10): `docker/docker-compose.cli.yml` `audit-migrate` / `progress-migrate` (commit `5655bfe8`); `memory-migrate` (P5 WP-5.3 — originally at commit `3630ae9d` in `docker-compose.services.yml`)
+- Spec: `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §ADR-INF-11 (full text)
+
+## ADR-INF-12 — DRY Alembic env.py via `vds_platform_core.alembic.runtime`
+
+**Status**: Accepted (P5 WP-5.2 — implemented at commit `2f8ec72c`) | **Spec**: `design.md` §ADR-INF-12
+
+All 4 DB-backed services (memory, audit, progress, scheduler) import their Alembic
+env.py runtime from `vds_platform_core.alembic.runtime`. Each service's `env.py` is
+~25-44 LOC of declarative configuration; the helper module is the single source of
+truth for psycopg-v3 dialect dispatch, asyncpg-aware DSN parsing, version_table_schema
+defaulting, and the SA2.0 implicit-tx safety contract.
+
+### Operator implications
+
+1. **Where the runtime logic lives**: `platform_core/src/vds_platform_core/alembic/runtime.py`. Debug Alembic failures here, not per-service `env.py` files.
+2. **Adding a new DB-backed service**: copy the canonical 25-44 LOC env.py shape from `scheduler_orchestrator/alembic/env.py`. See `infrastructure-evolution-skill/references/adding-a-new-service.md` for the 7-step onboarding.
+3. **Bug-fix-once propagation**: a fix in `runtime.py` propagates to all 4 services on next deploy. P5 WP-5.2 reduced cumulative env.py LOC from 621 → 330 (–301 LOC).
+
+→ Full rationale, API surface, rejected alternatives, references: `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §ADR-INF-12
+
+## ADR-INF-13 — PgBouncer Session-Mode Uniform Topology
+
+**Status**: Accepted (P8 WP-8.1–8.6 — deployed at `8948d1cf`, post-deploy fixes through `808ac1fb`) | **Spec**: `design.md` §ADR-INF-13
+
+Single-DSN routing through `vds-pgbouncer:6432` in session mode. Four per-database stanzas (`vds_audit`, `vds_memory`, `vds_progress`, `vds_sched`) each pin `search_path` via `connect_query`. No `_DIRECT_DSN` parallel; all services route uniformly.
+
+### Operator implications
+
+1. **Health**: `docker exec vds-pgbouncer psql -d pgbouncer -U pgbouncer_admin -c 'SHOW POOLS'` (port 6432).
+2. **Stanza edits**: require `docker compose restart vds-pgbouncer` to reload `pgbouncer.ini`.
+3. **Auth bootstrap**: `bash scripts/init-pgbouncer-userlist.sh` generates `userlist.txt` from live `pg_shadow`.
+
+→ Full rationale, topology rules, R12 escalation gate, operator one-liners, foot-guns: `.gpt-5.4/specs/ecosystem-infrastructure-evolution/design.md` §ADR-INF-13

package/skills/vds-skill/vds-scripts/docker/Dockerfile

@@ -0,0 +1,68 @@
+# syntax=docker/dockerfile:1
+# =============================================================================
+# VDS CLI (unified router) - Dockerfile
+# Phase: ecosystem-infrastructure-evolution v2.12.2 follow-up
+#
+# Build context: vds-scripts workspace root (per docker-compose.cli.yml)
+# Example: docker build -f docker/Dockerfile .
+#
+# Runtime contract:
+#   - vds-cli is the unified routed CLI for all VDS orchestrator commands
+#   - Reads ~/.vds/.env via env_file
+#   - CLI tool, not a long-running service (HEALTHCHECK polls vds-cli version)
+# =============================================================================
+
+FROM python:3.14.4-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_LINK_MODE=copy \
+    UV_COMPILE_BYTECODE=1 \
+    UV_PROJECT_ENVIRONMENT=/opt/venv \
+    PATH="/opt/venv/bin:$PATH"
+
+WORKDIR /app
+
+# System deps (curl for healthcheck; ca-certificates + git for outbound network/repo ops)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl ca-certificates git \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+# Workspace dep tree (per vds_cli/pyproject.toml [tool.uv.sources]):
+#   vds_cli
+#   ├── vds_cli_common (leaf)
+#   ├── vds_evolution → vds_cli_common
+#   ├── vds_bitbucket_orchestrator → vds_cli_common
+#   └── vds_google_sheets_orchestrator → vds_cli_common
+#
+# Copy all 5 in topological order (leaf-first).
+COPY vds_cli_common /app/vds_cli_common
+COPY vds_evolution /app/vds_evolution
+COPY bitbucket_orchestrator /app/bitbucket_orchestrator
+COPY google_sheets_orchestrator /app/google_sheets_orchestrator
+COPY vds_cli /app/vds_cli
+
+# Canonical workspace install pattern: per-path `uv pip install --no-sources`
+# (matches audit/progress/pdf/db-query/mcp-server Dockerfiles; avoids
+# per-package uv.lock requirement).
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv venv --python 3.14 /opt/venv && \
+    uv pip install --python /opt/venv/bin/python --no-sources \
+        /app/vds_cli_common \
+        /app/vds_evolution \
+        /app/bitbucket_orchestrator \
+        /app/google_sheets_orchestrator \
+        /app/vds_cli
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD /opt/venv/bin/vds-cli --help > /dev/null 2>&1 || exit 1
+
+ENTRYPOINT ["/opt/venv/bin/vds-cli"]
+CMD ["--help"]
+
+LABEL org.opencontainers.image.title="VDS CLI (unified router)" \
+      org.opencontainers.image.description="Unified routed CLI entry point for all VDS orchestrator commands" \
+      org.opencontainers.image.created="2026-04-26"