ultra-builder-pro-cli 0.25.0 → 0.26.0

package/skills/ultra-review/scripts/review_wait.py

@@ -2,8 +2,8 @@
 """Wait for and validate Ultra review v2 artifacts.
 
 Usage:
-    python3 review_wait.py <session_path> agents <artifact-stem> [<artifact-stem> ...]
-    python3 review_wait.py <session_path> summary
+    python3 review_wait.py <session_path> agents --packet-digest <sha256> <artifact-stem> [<artifact-stem> ...]
+    python3 review_wait.py <session_path> summary --packet-digest <sha256>
 
 The agents mode validates the exact named JSON files. The summary mode validates the
 two-axis verdict contract. Timeout and poll intervals can be shortened in tests with
@@ -96,13 +96,15 @@ def validate_finding(finding, artifact_axis: str, seen_ids):
     return None
 
 
-def validate_specialist(data):
+def validate_specialist(data, expected_packet_digest: str):
     if data.get("$schema") != FINDINGS_SCHEMA:
         return f"$schema must be {FINDINGS_SCHEMA}"
     if not nonempty_string(data.get("agent")):
         return "agent must be a non-empty string"
     if not digest_string(data.get("packet_digest")):
         return "packet_digest must be a lowercase SHA-256 digest"
+    if data["packet_digest"] != expected_packet_digest:
+        return f"packet_digest does not match expected immutable packet {expected_packet_digest}"
     axis = data.get("axis")
     if axis not in AXES:
         return "axis must be spec_fidelity or engineering_standards"
@@ -137,7 +139,7 @@ def validate_specialist(data):
     return None
 
 
-def evaluate_artifacts(session_path: Path, expected):
+def evaluate_artifacts(session_path: Path, expected, expected_packet_digest: str):
     done = []
     missing = []
     invalid = []
@@ -149,7 +151,7 @@ def evaluate_artifacts(session_path: Path, expected):
             continue
         data, error = read_json(path)
         if error is None:
-            error = validate_specialist(data)
+            error = validate_specialist(data, expected_packet_digest)
         if error:
             invalid.append(stem)
             errors[stem] = error
@@ -158,10 +160,12 @@ def evaluate_artifacts(session_path: Path, expected):
     return done, missing, invalid, errors
 
 
-def wait_for_agents(session_path: Path, expected, timeout: float) -> bool:
+def wait_for_agents(session_path: Path, expected, expected_packet_digest: str, timeout: float) -> bool:
     deadline = time.monotonic() + timeout
     while True:
-        done, missing, invalid, errors = evaluate_artifacts(session_path, expected)
+        done, missing, invalid, errors = evaluate_artifacts(
+            session_path, expected, expected_packet_digest
+        )
         if len(done) == len(expected):
             print(json.dumps({
                 "status": "complete",
@@ -195,7 +199,7 @@ def expected_overall_verdict(data) -> str:
     return "APPROVE"
 
 
-def validate_summary(data):
+def validate_summary(data, expected_packet_digest: str):
     if data.get("$schema") != SUMMARY_SCHEMA:
         return f"$schema must be {SUMMARY_SCHEMA}"
     if data.get("mode") not in REVIEW_MODES:
@@ -205,6 +209,8 @@ def validate_summary(data):
             return f"{field} must be a non-empty string"
     if not digest_string(data.get("packet_digest")):
         return "packet_digest must be a lowercase SHA-256 digest"
+    if data["packet_digest"] != expected_packet_digest:
+        return f"packet_digest does not match expected immutable packet {expected_packet_digest}"
     if data.get("worktree_digest") is not None and not nonempty_string(data.get("worktree_digest")):
         return "worktree_digest must be null or a non-empty string"
     task_ids = data.get("task_ids")
@@ -282,7 +288,7 @@ def validate_summary(data):
     return None
 
 
-def wait_for_summary(session_path: Path, timeout: float) -> bool:
+def wait_for_summary(session_path: Path, expected_packet_digest: str, timeout: float) -> bool:
     summary_path = session_path / "SUMMARY.json"
     deadline = time.monotonic() + timeout
     last_error = "SUMMARY.json is missing"
@@ -290,7 +296,7 @@ def wait_for_summary(session_path: Path, timeout: float) -> bool:
         if summary_path.exists():
             data, error = read_json(summary_path)
             if error is None:
-                error = validate_summary(data)
+                error = validate_summary(data, expected_packet_digest)
             if error is None:
                 counts = {severity: 0 for severity in sorted(SEVERITIES)}
                 for finding in data["findings"]:
@@ -319,19 +325,24 @@ def main():
         print(f"Error: session directory not found: {session_path}", file=sys.stderr)
         sys.exit(2)
 
+    if len(sys.argv) < 5 or sys.argv[3] != "--packet-digest" or not digest_string(sys.argv[4]):
+        print("Error: --packet-digest requires the expected lowercase SHA-256 digest", file=sys.stderr)
+        sys.exit(2)
+    expected_packet_digest = sys.argv[4]
+
     if mode == "agents":
-        expected = sys.argv[3:]
+        expected = sys.argv[5:]
         if not expected or len(expected) != len(set(expected)) or not all(
             ARTIFACT_STEM.fullmatch(stem) for stem in expected
         ):
             print("Error: agents mode requires unique safe artifact stems", file=sys.stderr)
             sys.exit(2)
-        ok = wait_for_agents(session_path, expected, DEFAULT_TIMEOUT)
+        ok = wait_for_agents(session_path, expected, expected_packet_digest, DEFAULT_TIMEOUT)
     elif mode == "summary":
-        if len(sys.argv) != 3:
-            print("Error: summary mode accepts no additional arguments", file=sys.stderr)
+        if len(sys.argv) != 5:
+            print("Error: summary mode accepts only --packet-digest", file=sys.stderr)
             sys.exit(2)
-        ok = wait_for_summary(session_path, DEFAULT_TIMEOUT)
+        ok = wait_for_summary(session_path, expected_packet_digest, DEFAULT_TIMEOUT)
     else:
         print(f"Error: unknown mode '{mode}'. Use 'agents' or 'summary'.", file=sys.stderr)
         sys.exit(2)

package/skills/ultra-status/SKILL.md

@@ -1,40 +1,65 @@
 ---
 name: ultra-status
-description: Read authoritative Ultra health, workflows, decisions, changes, tasks, evidence freshness, and team checkpoint state. Use when the user asks what is complete, blocked, stale, or currently possible.
+description: Infer the current Ultra workflow position, stale evidence, task risk, and installation health from repository files and host manifests. Use when the owner asks what is complete, blocked, stale, unhealthy, or useful to do next.
 ---
 
-# Report authoritative state
-
-This Skill is read-only.
-
-## Read
-
-Call `ultra.context { stage: project, detail: full }`. Use `ultra.sync { action:
-inspect }` only when the user needs team-checkpoint detail. Do not import, publish,
-repair, compile context, or mutate state.
-Never fall back to the Git team checkpoint, generated task JSON, or report files as
-live authority when `ultra.context` reports missing or unhealthy local state.
-
-Report:
-
-```text
-Ultra: <healthy|degraded> · <branch>@<head|unborn|non-git>
-Baseline: <mode>/<status> · gaps=<open>/<blocking>
-Stage checkpoints: drafts=<count> · accepted=<current|stale|none>
-Change: <id/status|none> · delta/docs=<state>
-Task: <id/status|none> · Sessions: <active>
-Evidence: plan=<state> · test=<state> · review=<axes> · delivery=<state>
-Team checkpoint: <current|drifted|revalidation_required|missing|invalid>
-Blockers: <hard mechanical blockers or none>
-Warnings: <advisory semantic diagnostics or none>
-Model recommendation: <capability and concise rationale>
-```
-
-Treat warnings and failed draft checks as information, not mechanical orders. Only
-corruption, unsafe paths, real concurrency conflicts, permissions, or irreversible
-external effects are hard blockers.
-
-The host model recommends the next useful capability from accepted intent, current
-evidence, cost of interruption, and owner goal. SQLite does not choose the route.
-Separate verified facts, model inference, and unavailable evidence. Never invoke the
-recommendation automatically.
+# Route from artifacts without changing them
+
+This router is read-only. It reports verified files, model inference and unavailable
+evidence separately, then recommends one explicit capability without invoking it.
+
+## Before you start
+
+1. Read `.ultra/tasks.json` if present; read the active task's `context_file` and
+   closing `## Resume Note`.
+2. Read `CONTEXT.md` and relevant `.ultra/decisions/` entries when they exist.
+3. Inspect Git `HEAD`, worktree status, active/archive Change directories and installed
+   host manifests without repairing them.
+
+## Definition of done
+
+- The artifact route below is evaluated in order and the matching evidence is named.
+- Stale test evidence, dirty worktree state and task graph risks are visible.
+- Installation health reports exact missing or drifted files without mutation.
+- The recommendation says why it follows; it does not launch the capability.
+
+## Infer the route
+
+| Observable files | Recommendation |
+|---|---|
+| No `.ultra/` | `ultra-init` |
+| Product specification missing or contains `[NEEDS CLARIFICATION]` | `ultra-research` |
+| A new request exists and no active Change exists | `ultra-change` |
+| An active Change exists and `.ultra/tasks.json` is missing or `tasks` is empty | `ultra-plan` |
+| A frontier task is pending or in progress | `ultra-dev`, naming the task |
+| All tasks completed and no current report | `ultra-test` |
+| `test-report.passed` is false | `ultra-dev`, with blocking findings |
+| Report passed and `git_commit` equals `HEAD` | `ultra-deliver` |
+| No active Change and no new request | Report the idle state; do not manufacture work |
+
+A report whose `git_commit` differs from `HEAD`, or whose recorded `worktree.diff_digest`
+differs from the result of resolving the installed `ultra-test` Skill and running
+`node <ultra-test-skill-dir>/scripts/worktree_digest.cjs --project <repository-root>`, is stale. A dirty
+worktree is a warning, not evidence of failure.
+
+## Surface risk and installation health
+
+List unmet task dependencies, any `in_progress` task older than 3 days, complexity
+concentration and broken `trace_to` or `context_file` paths. These are sensors.
+
+For installation health, compare the selected host's plugin path, skill inventory,
+version, provenance and hook manifest against the installed files. Report broken links
+and missing registrations. Recommend `ubp install` or `ubp update` as the reachable
+repair; this read-only skill never performs it.
+
+## When the owner decides
+
+The owner chooses the next workflow, risk disposition and any reinstall. Contradictory
+file facts are reported as contradictions rather than silently selecting one.
+
+## References
+
+- `../ultra-think/SKILL.md` — read only when contradictory evidence creates a real
+  decision rather than a mechanical repair.
+- `../ultra-think/references/autonomy-boundary.md` — read before recommending a route
+  that would reduce an accepted commitment.

package/skills/ultra-tdd/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ultra-tdd
+description: Drive one slice of behavior through red then green — a failing test on a confirmed seam, then the smallest code that passes it. Use when another skill is about to write or change behavior and needs the feedback loop that proves the code actually runs, including a small change that goes straight to implementation.
+---
+
+# Write one failing test on a seam, then just enough code to pass it
+
+Without feedback from code that actually ran, the work is blind flying. This is
+the loop that supplies it, and it serves Goal 3, Production-Ready.
+
+## Before you start
+
+1. Read the current task context for the seams already confirmed during
+   planning. Tests live on those, and choosing a new one is a planning decision.
+2. Run the repository's existing test command once, unchanged, to see what
+   passing currently looks like. Read `references/test-execution.md` before recording
+   that run or any red/green evidence.
+3. Read `CONTEXT.md` for vocabulary — test names carry the domain words.
+
+## Definition of done
+
+- One slice is complete: one seam, one test, one minimal implementation.
+- The test was observed failing before the implementation existed, and observed
+  passing after. Both runs are real command output.
+- The test reads as a specification of behavior through a public interface, and
+  survives replacing the implementation underneath it.
+
+## Seams, and what a good test on one looks like
+
+A seam is a place where behavior can change without editing at that place — the
+module interface. Tests live on seams and never reach for internals. Prefer a
+seam that already exists, take the highest one that works, and one is the ideal
+number. Verify behavior through that public interface: a name like "user can
+checkout with a valid cart" shows at a glance what capability exists, and one
+logical assertion per test keeps it readable.
+
+## Red, then green
+
+Write the failing test first and run it, so that red is observed rather than
+assumed. Then write the smallest code that turns it green. Predict no later
+tests and add no speculative capability. Then take the next slice.
+
+Refactoring is not part of this loop; `ultra-review` owns it, because the
+restructuring worth doing only becomes visible after three or four slices.
+
+## Three patterns that produce tests worth deleting
+
+| Pattern | How you recognize it |
+|---|---|
+| Implementation-coupled | Mocks an internal collaborator, tests a private method, asserts on call counts or ordering, or reaches past the interface into the database. The check: behavior is unchanged after restructuring, yet the test breaks. |
+| Tautological | Recomputes the expected value the same way the implementation does, so it can never fail. Expected values come from an independent source — a known literal, a hand-worked example, the specification. |
+| All tests first | Writing every test before any implementation tests imagined behavior. It captures shape rather than user-visible behavior, is insensitive to real change, and freezes the test structure before the implementation is understood. Take one test, one implementation, and repeat. |
+
+## Mock only at the system boundary
+
+External APIs, time and randomness, sometimes the filesystem. Prefer a real test
+library over mocking the database. Your own classes, modules and internal
+collaborators stay real.
+
+Design for that boundary: inject dependencies, and give each external operation
+its own named function rather than one generic fetcher — mocking then needs no
+conditional logic, and which endpoints a test touches stays visible. When a real
+dependency is the right answer, copy
+`references/templates/testcontainer-postgres.ts` or
+`references/templates/testcontainer-postgres.py`, and
+`references/templates/vertical-slice.ts` for a path that runs end to end.
+
+## When the owner decides
+
+Weakening an assertion, skipping a relevant test, or adjusting an expected value
+to obtain green output crosses the C5 boundary — stop and surface it. A test that
+is genuinely wrong about the specification is a specification question, so it
+goes to the owner as one.
+
+## References
+
+- `../ultra-think/references/autonomy-boundary.md` — read before replacing a real
+  dependency with a fake, or when a test stands between the work and green.
+- `references/templates/README.md` — read when choosing which enabling template
+  fits the dependency you need to make real.
+- `references/test-execution.md` — exact command, failure and result evidence contract.

package/skills/ultra-tdd/references/templates/README.md

@@ -0,0 +1,20 @@
+# Enabling templates
+
+These runnable examples make the real integration path cheaper than a fake. Read this
+index when `ultra-tdd` reaches a database, feature flag, or multi-layer seam, then copy
+only the smallest relevant file into the project and adapt it to repository conventions.
+
+| Template | When to copy |
+|---|---|
+| [testcontainer-postgres.ts](testcontainer-postgres.ts) | A TypeScript/Node test needs real Postgres instead of an internal Repository mock |
+| [testcontainer-postgres.py](testcontainer-postgres.py) | A pytest test needs real Postgres instead of a `MagicMock` Repository |
+| [vertical-slice.ts](vertical-slice.ts) | One test must prove HTTP → use case → database → response |
+| [persistence-real.ts](persistence-real.ts) | A Repository needs real storage rather than an in-memory `Map` |
+| [feature-flag-default-audit.sh](feature-flag-default-audit.sh) | A Change must surface default-off flags that could hide unfinished work |
+
+The templates travel with the `ultra-tdd` skill; they are rule-side examples, not
+project authority. Do not copy this directory wholesale into `.ultra/`.
+
+Each template must remain runnable after its documented dependencies are installed,
+name the exact verification command in its header, stay short enough to inspect before
+use, and state which Ultra principle makes the example preferable.

package/skills/ultra-tdd/references/templates/feature-flag-default-audit.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# feature-flag-default-audit.sh
+#
+# Surface every `default off` / `enabled: false` / commented-out feature so the
+# user knows what is *quietly* disabled. Catches the "agent shipped task by
+# turning the feature off" failure mode v7 fixes.
+#
+# Usage:
+#   bash feature-flag-default-audit.sh [path]
+#
+# Default path: src/  (override with first arg)
+#
+# PHILOSOPHY: enables C5 (Bounded Autonomy) — default-off without rationale is
+# scope reduction in disguise; this surfaces it so the user can decide.
+
+set -euo pipefail
+
+ROOT="${1:-src}"
+if [ ! -d "$ROOT" ]; then
+  echo "[audit] path not found: $ROOT" >&2
+  exit 1
+fi
+
+echo "## Feature-flag default audit"
+echo "Path: $ROOT"
+echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo ""
+
+# Patterns we care about. Adjust per project conventions.
+patterns=(
+  '\benabled:\s*false\b'
+  '\bdefault\s*[:=]\s*false\b'
+  '\bDISABLED\s*=\s*true\b'
+  '\bif\s*\(\s*false\s*\)'
+  'FEATURE_[A-Z_]+\s*=\s*false'
+)
+
+found_any=0
+for p in "${patterns[@]}"; do
+  hits=$(grep -REn "$p" "$ROOT" \
+    --include='*.ts' --include='*.tsx' \
+    --include='*.js' --include='*.jsx' \
+    --include='*.py' --include='*.go' \
+    --include='*.rs' --include='*.sol' \
+    --include='*.yaml' --include='*.yml' \
+    --include='*.json' --include='*.toml' 2>/dev/null || true)
+
+  if [ -n "$hits" ]; then
+    found_any=1
+    echo "### Pattern: $p"
+    echo '```'
+    echo "$hits"
+    echo '```'
+    echo ""
+  fi
+done
+
+# Also surface TODO-style "off until later" markers
+todo_hits=$(grep -REn '(TODO|FIXME).*(enable|turn on|flip on)' "$ROOT" 2>/dev/null || true)
+if [ -n "$todo_hits" ]; then
+  found_any=1
+  echo "### TODOs to re-enable later"
+  echo '```'
+  echo "$todo_hits"
+  echo '```'
+  echo ""
+fi
+
+if [ "$found_any" -eq 0 ]; then
+  echo "_No default-off features detected._"
+  exit 0
+fi
+
+echo "---"
+echo ""
+echo "**Action**: For each entry above, confirm with the user whether it is:"
+echo "- (A) Pre-launch: feature is built but gated until release — fine"
+echo "- (B) Genuine kill-switch: stays off in normal operation — fine, document why"
+echo "- (C) Hiding incomplete work: agent shipped task by turning it off — **must fix**"

package/skills/ultra-tdd/references/templates/persistence-real.ts

@@ -0,0 +1,78 @@
+/**
+ * Real-persistence Repository skeleton (TypeScript)
+ *
+ * Why this exists: in-memory `Map` Repositories are a v7 anti-pattern. They
+ * pass tests, don't survive restart, hide migration bugs, and silently break
+ * production. This template shows the minimum real Repository.
+ *
+ * Required deps:
+ *   pnpm add pg
+ *   # Optional ORM: drizzle / prisma / kysely
+ *
+ * PHILOSOPHY: enables C4 progress.json `persistence_real` dimension. Pair with
+ * testcontainer-postgres.ts for the test side.
+ */
+
+import type { Pool, PoolClient } from 'pg';
+
+// Domain entity — keep separate from row shape
+export type User = {
+  id: number;
+  email: string;
+  createdAt: Date;
+};
+
+// Optional: row→entity mapper if column names differ from field names
+function rowToUser(row: { id: number; email: string; created_at: Date }): User {
+  return { id: row.id, email: row.email, createdAt: row.created_at };
+}
+
+export class UserRepo {
+  constructor(private readonly pool: Pool) {}
+
+  async create(input: { email: string }): Promise<User> {
+    const { rows } = await this.pool.query<{
+      id: number;
+      email: string;
+      created_at: Date;
+    }>(
+      `INSERT INTO users (email) VALUES ($1)
+       RETURNING id, email, created_at`,
+      [input.email],
+    );
+    return rowToUser(rows[0]);
+  }
+
+  async findById(id: number): Promise<User | null> {
+    const { rows } = await this.pool.query<{
+      id: number;
+      email: string;
+      created_at: Date;
+    }>(
+      `SELECT id, email, created_at FROM users WHERE id = $1`,
+      [id],
+    );
+    return rows[0] ? rowToUser(rows[0]) : null;
+  }
+
+  // Multi-statement work — pass in a client to keep it on a single connection
+  async withTransaction<T>(work: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await this.pool.connect();
+    try {
+      await client.query('BEGIN');
+      const result = await work(client);
+      await client.query('COMMIT');
+      return result;
+    } catch (e) {
+      await client.query('ROLLBACK');
+      throw e;
+    } finally {
+      client.release();
+    }
+  }
+}
+
+// What this template intentionally does NOT do (and why):
+// - No `Map<number, User>` field. That is the in-memory anti-pattern v7 surfaces.
+// - No silent error swallowing (catch + return-null). Errors propagate; callers handle.
+// - No mock-friendly singleton. Inject the Pool so testcontainers work cleanly.

package/skills/ultra-tdd/references/templates/testcontainer-postgres.py

@@ -0,0 +1,78 @@
+"""
+Testcontainer-Postgres starter (Python / pytest)
+
+Why this exists: Real DB in tests catches migration drift, schema bugs, and
+concurrency issues that mocked Repositories silently miss. Prefer this to
+`MagicMock(spec=Repo)` for any Repository or Service that touches data.
+
+Required deps:
+    pip install testcontainers[postgres] psycopg[binary] pytest
+
+Verify:
+    pytest tests/repo/test_user_repo_testcontainer.py -v
+
+PHILOSOPHY: enables C2 (Enabling > Defensive) — the cheaper path becomes the
+right path, so agents stop reaching for mocks under pressure.
+"""
+
+from __future__ import annotations
+
+import psycopg
+import pytest
+from testcontainers.postgres import PostgresContainer
+
+
+@pytest.fixture(scope="module")
+def pg():
+    """Module-scoped real Postgres. Slow on first pull, fast after."""
+    with PostgresContainer("postgres:16-alpine") as c:
+        with psycopg.connect(c.get_connection_url()) as conn:
+            with conn.cursor() as cur:
+                cur.execute("""
+                    CREATE TABLE users (
+                        id SERIAL PRIMARY KEY,
+                        email TEXT UNIQUE NOT NULL,
+                        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+                    );
+                """)
+            conn.commit()
+        yield c
+
+
+@pytest.fixture
+def conn(pg):
+    """Per-test connection with truncate-reset so each test is independent."""
+    with psycopg.connect(pg.get_connection_url()) as c:
+        with c.cursor() as cur:
+            cur.execute("TRUNCATE users RESTART IDENTITY CASCADE")
+        c.commit()
+        yield c
+
+
+def make_user_repo(conn):
+    """Replace with import from your real Repository."""
+    class UserRepo:
+        def create(self, email: str) -> dict:
+            with conn.cursor() as cur:
+                cur.execute(
+                    "INSERT INTO users (email) VALUES (%s) RETURNING id, email, created_at",
+                    (email,),
+                )
+                row = cur.fetchone()
+            conn.commit()
+            return {"id": row[0], "email": row[1], "created_at": row[2]}
+
+        def find_by_id(self, user_id: int) -> dict | None:
+            with conn.cursor() as cur:
+                cur.execute("SELECT id, email, created_at FROM users WHERE id = %s", (user_id,))
+                row = cur.fetchone()
+            return None if row is None else {"id": row[0], "email": row[1], "created_at": row[2]}
+
+    return UserRepo()
+
+
+def test_insert_and_fetch_round_trips(conn):
+    repo = make_user_repo(conn)
+    created = repo.create("a@example.com")
+    found = repo.find_by_id(created["id"])
+    assert found == created

package/skills/ultra-tdd/references/templates/testcontainer-postgres.ts

@@ -0,0 +1,73 @@
+/**
+ * Testcontainer-Postgres starter (TypeScript / vitest or jest)
+ *
+ * Why this exists: Real DB in tests catches migration drift, schema bugs, and
+ * concurrency issues that mocked Repositories silently miss. Prefer this to
+ * `jest.fn()` / `vi.fn()` for any Repository or Service that touches data.
+ *
+ * Required deps:
+ *   pnpm add -D @testcontainers/postgresql pg
+ *
+ * Verify:
+ *   pnpm vitest run src/repo/__tests__/userRepo.testcontainer.test.ts
+ *
+ * PHILOSOPHY: enables C2 (Enabling > Defensive) — the cheaper path becomes the
+ * right path, so agents stop reaching for mocks under pressure.
+ */
+
+import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
+import { Pool } from 'pg';
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'vitest';
+
+let container: StartedPostgreSqlContainer;
+let pool: Pool;
+
+beforeAll(async () => {
+  container = await new PostgreSqlContainer('postgres:16-alpine').start();
+  pool = new Pool({ connectionString: container.getConnectionUri() });
+  // Replace with your migration runner (drizzle/prisma/knex/raw SQL)
+  await pool.query(`
+    CREATE TABLE users (
+      id SERIAL PRIMARY KEY,
+      email TEXT UNIQUE NOT NULL,
+      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    );
+  `);
+}, 60_000); // pulling postgres image can be slow on first run
+
+afterAll(async () => {
+  await pool.end();
+  await container.stop();
+});
+
+beforeEach(async () => {
+  // Reset between tests so each is independent
+  await pool.query('TRUNCATE users RESTART IDENTITY CASCADE');
+});
+
+describe('UserRepo (real Postgres)', () => {
+  test('insert and fetch round-trips', async () => {
+    // Replace with your actual Repository
+    const repo = makeUserRepo(pool);
+    const created = await repo.create({ email: 'a@example.com' });
+    const found = await repo.findById(created.id);
+    expect(found).toEqual(created);
+  });
+});
+
+// Drop your real Repository factory here
+function makeUserRepo(pool: Pool) {
+  return {
+    async create(input: { email: string }) {
+      const { rows } = await pool.query(
+        'INSERT INTO users (email) VALUES ($1) RETURNING *',
+        [input.email],
+      );
+      return rows[0];
+    },
+    async findById(id: number) {
+      const { rows } = await pool.query('SELECT * FROM users WHERE id = $1', [id]);
+      return rows[0] ?? null;
+    },
+  };
+}