feat(comms): content strategy and Comms agent infrastructure

[ohld]

Summary

Content strategy for @ffmemes Telegram channel with daily posting cadence (~1 post/day). Comms Manager agent is now operational with content plan, brand guide, and posting infrastructure.

Content & Brand

• docs/comms/content-plan.md — ~30 post ideas across 6 categories (Feature Spotlights, Lore, Data Insights, Engagement, Recurring, Behind-the-scenes)
• docs/comms/brand-guide.md — Colors (#FF6B35 primary), Work Sans font, chart palette, visual formats
• docs/comms/lore/ — vc.ru origin story archive with then-vs-now comparison (Oct 2020 → Mar 2026)

Posting Infrastructure

• src/flows/crossposting/editorial.py — On-demand Prefect flow for text/photo editorial posts with optional inline buttons
• src/flows/crossposting/weekly_report.py — Sunday 14:00 MSK burger economy snapshot (minted/spent/top earners)
• Both registered in scripts/serve_flows.py

Giveaway System

• src/tgbot/handlers/treasury/giveaway.py — Deep link handler for ?start=giveaway_77
• Campaign whitelist prevents unlimited burger minting (Codex review catch)
• Runs after onboarding for new users so user_language rows exist (Codex review catch)
• TrxType.GIVEAWAY with 77 burger payout

Agent Config

• agents/.paperclip.yaml — ANALYST_DATABASE_URL for Comms agent DB queries
• src/tgbot/constants.py — ADD_TO_GROUP_DEEPLINK for "add to chat" CTA posts

Pre-Landing Review

Codex review found and we fixed 3 issues:

• [P1] Unlimited burger minting via crafted giveaway links → whitelist of active campaigns
• [P2] New users skipping onboarding via giveaway deep link → giveaway runs after init
• [P3] Cron schedule 11:00 MSK instead of documented 14:00 MSK → fixed to 0 14 * * 0

Test plan

• Deploy and verify editorial Prefect flow appears in dashboard
• Test ?start=giveaway_77 deep link credits burgers
• Test ?start=giveaway_fake does NOT credit burgers
• Verify weekly report flow runs manually via Prefect CLI
• Comms agent drafts first post using content plan

[ohld]

Staff Engineer Review — 4 issues (3 critical, 1 informational)

Codex structured + adversarial pass both flagged these. 3 issues need fixes before merge.

---

[P1] Weekly burger report counts transfers as "minted"

weekly_report.py:21-28 — amount > 0 matches all positive rows, including:

• RECEIVE rows from user-to-user transfers (service.py:95 — recipient gets a positive row)
• Treasury credit rows from BOT_REPLY_PAYMENT charges (payments.py:59)

Result: "Выпущено" will be inflated on any week with transfers or bot-reply payments, and TREASURY_USER_ID can appear in the top-earners leaderboard. A public channel report with wrong numbers.

Fix: Add AND type NOT IN ('send', 'receive', 'bot_reply_payment') AND user_id != 1123681771 to minted/earners queries, or filter to an explicit allowlist of minting types.

---

[P1] Race condition in giveaway claim

giveaway.py:49 — pay_if_not_paid does read-then-insert across two separate statements with no unique constraint on (user_id, type, external_id) in treasury_trx. Two concurrent /start giveaway_77 requests (double-tap) can both observe "not paid" and each mint +77. This is a public deep link with real money.

Fix: Add UniqueConstraint("user_id", "type", "external_id") to treasury_trx (with a migration). This fixes the pattern across all callers, not just giveaway.

---

[P2] New users via giveaway deep link get two memes (double delivery)

start.py:106-109 — For new users, handle_giveaway calls next_message (meme #1) BEFORE the user has responded to the language selection keyboard. When the user picks a language, handle_language_settings_end → onboarding_flow checks nmemes_sent <= 3 (true), runs the welcome countdown, and sends meme #2.

Every new user entering via ?start=giveaway_77 gets: language selector → giveaway confirm → meme → welcome animation → duplicate meme.

Fix: Defer giveaway payout to handle_language_settings_end after onboarding completes, or pass giveaway context through conversation state.

---

[P3] Editorial channel fallback silently posts to EN on invalid input

editorial.py:49 — Any channel value other than exact "ru" routes to EN. A typo ("RU", empty string, Prefect parameter mismatch) won't error — it will silently post to the wrong production channel.

Fix:

if channel not in ("ru", "en"):
    raise ValueError(f"Unknown channel: {channel!r}")

---

Lint fixes already pushed in 1c6af45. The pre-existing lint/test failures on production are unrelated to this PR.

[ohld]

CI Status & Review

CI is failing, but investigation shows these are pre-existing failures on production — not regressions from this PR.

Failures (not introduced by this PR)

• lint — tests/recommendations/test_meme_queue.py: unsorted imports (I001) and long lines (E501). File not modified by this PR.
• test — tests/recommendations/test_engine_contracts.py: TypeError: fixture() got an unexpected keyword argument 'loop_scope' (pytest-asyncio version incompatibility). File not modified by this PR.

Confirmed: last 5 CI runs on production all fail — this is pre-existing breakage.

PR Changes Assessment

The comms infrastructure changes are solid:

• Content plan, brand guide, lore archive ✓
• Editorial and weekly report Prefect flows ✓
• Giveaway handler with campaign whitelist (security fix) ✓
• Giveaway runs after onboarding init (correctness fix) ✓
• Cron fixed to 0 14 * * 0 (14:00 MSK Sundays) ✓

Merging — CI failures are a separate pre-existing issue to fix on production.