popagent

public

Latest change 7f0ff66d6d9fb6468416c58bee46bd3d08169501 - Checkpoint browser channels and memory work by AkurAI Build

---
name: popagent-database-change
description: Implement and verify popagent PostgreSQL schema, migration, persistence, retention, and database-backed settings changes. Use for SQL files, stores, repository classes, or APIs that alter durable data semantics.
---

# Popagent database change

Read `../../../AGENTS_AGENT.md`, `../../../AGENTS_RULES.md`, and the relevant domain file before editing. For memory changes, also read `../../../AGENTS_MEMORY.md`; for hook audit changes, read `../../../AGENTS_HOOKS.md`.

1. Identify the existing schema initializer, migration marker, store, and owning contract test before changing code.
2. Preserve PostgreSQL as the runtime source of truth. Do not introduce SQLite, code fallback rows, or startup reseeding that overwrites user-managed data.
3. Make migrations versioned, retry-safe, and safe under concurrent initialization. Singleton configuration rows are seeded exactly once and missing rows after migration are configuration errors.
4. Preserve resource/workspace boundaries, deletion semantics, retention limits, and optimistic concurrency where applicable.
5. Follow red-green-refactor: add or update the narrow database contract test and run it to observe the intended failure before changing implementation. Use only a disposable local PostgreSQL database; never point tests at durable production data.
6. Run the narrow test first, then affected tests, `bunx tsc --noEmit`, and finally `bun test` when the required services are available.
7. Update the relevant `AGENTS_*.md` file for changed schema or behavior, removing stale guidance rather than appending history.

Never place credentials in fixtures, logs, committed environment files, or generated artifacts.