docs: agent & strategy persistence design + plan

[FlyM1ss]

Approved design spec + task-by-task implementation plan for making user-created content survive Render redeploys: external_agents, agent_versions, and strategies get optional Postgres backends behind one new env var CONTENT_DATABASE_URL, cloning the shipped USERS_DATABASE_URL users fix (hand-written twin class per store, per-module factory, singletons unchanged). Deliberately not named DATABASE_URL — that is the Heroku-convention name add-ons inject and unrelated projects export, and an ambient value would silently bind the app to the wrong database.

Docs only — no code changes; safe to merge on its own. Implementation lands in a follow-up PR off the plan (docs/superpowers/plans/2026-07-15-agent-strategy-persistence.md), which opens as a draft and carries its own gate: CONTENT_DATABASE_URL must be set in the Render dashboard before that PR merges (unset silently selects ephemeral SQLite).

🤖 Generated with Claude Code

https://claude.ai/code/session_01VPTbEcj871EPmEyXwJb2Fi

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentic-trading-lab	Ready	Preview, Comment	Jul 15, 2026 5:58am

[FlyM1ss]

Reviewed this branch and pushed the fixes as 515dc91. Six findings; five from the review, one found while adversarially verifying the fixes — that one defeated another fix, so it's the important one.

The Postgres half would have shipped to prod unexecuted. CI has no services: block, so TEST_POSTGRES_URL is never set and every @pg_only test skips on every PR — and the plan called running them locally "optional". Prod's first execution is _init_schema() at import time under fail-loud semantics, on a free tier with no zero-downtime deploys, so a DDL typo is an outage rather than a bug. New Task 2 adds a postgres:16-alpine service + a guard test, so dropping the block later fails loudly instead of silently reverting to all-skip.

logger.info() is dead code in this app. uvicorn's LOGGING_CONFIG has no root key, nothing under dashboard/backend/ configures logging, and no launch path passes --log-level — so dashboard.backend.* loggers sit at WARNING and isEnabledFor(INFO) is False. Every dispatch test would have been green anyway, because caplog.at_level() force-sets the level for the test. Green suite, silent prod — the exact failure this feature exists to kill, reintroduced by the fix meant to prevent it. All four factories now print() (the convention in ~25 modules here, including app.py's startup block), and tests assert on capsys.

backend: postgres couldn't say which postgres. DATABASE_URL is the most collision-prone name in the ecosystem, and the line read identically for the intended Neon DB and a stray one. New Task 3 adds db_url.py::describe_database_url() → host[:port]/dbname, defined once because it's credential-scrubbing code. (Its first draft leaked: urlsplit dumps a psycopg keyword/DSN string — password and all — into .path, so the "safe" fallback would have logged the credential verbatim. It now keys off hostname and echoes nothing.) The env var name stays DATABASE_URL — that was a settled decision — with the residual risk documented and CONTENT_DATABASE_URL recorded as the escape hatch.

Also: "fail loud" was a hard constraint with zero tests (added one per twin — no live Postgres needed, and it's the only tier that runs a twin's real __init__); test_strategy_store.py already exists at tests/domain/strategies/ and the plan said "Create" it at tests/, so that's now Modify; the spec/plan ALTER-migration contradiction is reconciled; the PR now opens as a draft with the DO NOT MERGE gate in its first line, since a gate living only in a plan file is not a gate; and a miscited test was dropped before it shipped into a committed docstring.

Verified rather than asserted: describe_database_url + its tests run green; psycopg raises OperationalError on a refused port in 0.00s; the collision tests pass against the real StrategyStore (calls == 21); the CI yaml parses and deploy-prod cannot fire from a draft PR; and print() survives uvicorn's real config where logger.info() doesn't.

Still docs-only and safe to merge. Task count went 7 → 9.

[FlyM1ss]

f911884 — renamed the content-store env var DATABASE_URL → CONTENT_DATABASE_URL, which reverses Decision 2's naming call and takes the escape hatch the spec itself had recorded.

Two settled changes:

1. Scoped name. DATABASE_URL is the Heroku de-facto standard — auto-injected by managed-Postgres add-ons, plausibly already exported in a dev's shell for another project. Nothing can protect a local uvicorn run from an ambient value (reading the env var is the feature), so the collision is designed out of the name rather than merely logged.

2. Users fallback dropped (the "cost of the one-var goal" the old Decision 2 predicted). USERS_DATABASE_URL and CONTENT_DATABASE_URL are scoped per store and never resolve against each other — a var named for content shouldn't select the account database. A fully durable deployment sets both, pointed at the same Neon DB. Prod already sets USERS_DATABASE_URL, so its behavior is unchanged; rollout still only needs the one new var added in the Render dashboard.

Not a find/replace — the prose that argued for the old name was rewritten:

• Decision 2 now reads as a settled choice. Its log-line rationale is re-anchored to typo'd/staging URLs and the unset→SQLite branch — the risks the rename does not address — so a later reader can't conclude the rename made the host/dbname log line redundant.
• Task 4 shrinks from "build the fallback + log line" to "log line only" (users.py:313 already reads USERS_DATABASE_URL alone, so selection genuinely doesn't change). Its two fallback tests are replaced by one inverted test pinning that the users factory ignores CONTENT_DATABASE_URL — otherwise re-adding the fallback would pass green.
• Task 1's urgency recalibrated honestly: a scoped name narrows the ambient trigger, though the strip is still worth its two lines and its .db_path job is unaffected.

Verified with a 4-lens review + adversarial refutation, which caught two mechanical-rename leftovers I'd missed (Task 3's intro and the File Structure table both still called the new name "the most collision-prone name in the ecosystem" / "Precedence"); a follow-up grep caught a third in describe_database_url()'s docstring. All three fixed. No code changes — docs only.