| name | poly-dev-manager |
| description | Top-level router for Cogni's Polymarket poly node. Load this skill for any poly work; it routes you to the right specialty skill (copy-trading loops, market-data / CLOB / Data-API, or auth & wallets). Use when starting a poly task, triaging a poly bug, reviewing a poly PR, or anytime the work smells poly-adjacent but you don't yet know which sub-domain. Also triggers for: 'work on the poly node', 'poly bug', 'review this poly PR', 'what does the poly node do', 'which poly skill do I need', 'poly roadmap', 'Phase 3 / Phase 4', 'task.0318 / task.0315 / task.0322', 'mirror trade Polymarket wallet', 'fix poly in candidate-a'. |
Poly Dev Manager
You are the orientation layer for Cogni's poly node. This file is intentionally short: it gets you to the specialty skill you actually need.
What the poly node does (one paragraph)
Takes a Polymarket wallet that demonstrably trades with edge and mirrors its fills onto a Cogni-controlled trading wallet. Target wallet trades → wallet-watch detects (Data-API /trades poll, with WS wake-up after #1172) → mirror-coordinator decides → INSERT_BEFORE_PLACE ledger row lands → PolymarketClobAdapter signs via Privy HSM → CLOB receipt. v0 shipped single-operator; Phase A shipped RLS on copy-trade tables; Phase B (task.0318, deploy_verified 2026-04-22) shipped per-tenant Privy trading wallets. Phase 4 (task.0322) will swap the 30s poll for CLOB WebSocket + adversarial-robust target ranking.
Current Status Card (2026-05-06)
Where the work is right now: the mirror loop is stable; energy has shifted to the research / data-science surface and the historical backfill that powers it. Most active code lives under nodes/poly/app/src/features/wallet-analysis/server/ and app/(app)/research/, not in the mirror coordinator. When in doubt about where a new task belongs, default to: trading-algorithm tuning ⇒ poly-copy-trading; building or querying a research view ⇒ data-research; backfill / data-coverage gap ⇒ both.
Recent ground-shifts to know before editing anything:
- SQL-aggregation is the standard for any read over
poly_trader_fills / poly_trader_position_snapshots / poly_market_*. bug.5012 (2026-05-05) — poly OOM-crashlooped on RN1's 825k-fill backfill; fix was a per-field SQL refactor of wallet-analysis-service.ts across cp1–cp7. Naively writing db.select().from(polyTraderFills).where(...) is the canonical anti-pattern. See data-research.
- Backfill is the live operational concern. Several derived tables (
poly_trader_position_snapshots, poly_market_metadata, poly_market_outcomes, poly_market_price_history) started writing only May 1–5; pre-cutover history must be backfilled from poly_trader_fills (SQL-derived), poly_copy_trade_decisions.receipt (JSONB-derived), or Polymarket APIs (reuse the forward-fill writer with a one-shot driver — never hand-rolled). See coverage caveats in the operational-data-tables block below.
- Canonical market-metadata table (#1265, #1270).
poly_market_metadata is now the source of titles/event metadata. Older code paths that decoded titles out of jsonb on every query are being retired.
- Research tab is the active product surface. target-overlap, market-exposure, P/L overlay, target-size PnL, trader-comparison, copy-target benchmarks, market-aggregation views all landed since #1215. New views must follow
data-research.
Active copy-trade behavior (mirror policy v0):
- New entries for curated targets use
target_percentile_scaled: the target condition/token position cost basis must be at or above that wallet's configured pXX threshold before we mirror it.
- Default pXX is p75. p50/p75/p90/p95/p99 are hardcoded; unsupported values interpolate between known points and clamp outside the known range.
- Accepted BUY branches size from market minimum toward
max_usdc_per_trade, scaled by how far the target position is between pXX and p99.
- Existing mirror positions add branch context through
position_followup: same-token layer, opposite-token hedge, SELL sell_close. Follow-ups still respect market floors, per-position caps, local mirror exposure thresholds, idempotency, tenant grant authorization, and CLOB placement checks.
Hardcoded position pXX baked into bootstrap config (still current as of 2026-05-06):
| target | p50 | p75 | p90 | p95 | p99 | sample |
|---|
| RN1 | $40 | $200 | $733 | $1,811 | $5,659 | 3,990 token positions, Data API /positions?sizeThreshold=0, captured 2026-05-03T02:34Z |
| swisstony | $31 | $146 | $665 | $1,394 | $4,809 | 1,085 token positions, Data API /positions?sizeThreshold=0, captured 2026-05-03T02:34Z |
Position follow-up defaults: min_mirror_position_usdc=5, market_floor_multiple=5, min_target_hedge_ratio=0.02, min_target_hedge_usdc=5, max_hedge_fraction_of_position=0.25, max_layer_fraction_of_position=0.5. Source of truth: nodes/poly/app/src/bootstrap/jobs/copy-trade-mirror.job.ts. Re-flight after any edit to that file.
Observability reality: Loki is the current operational truth. Query event="poly.mirror.decision" for processed fills; position-aware branches include position_branch, position_qty_shares, position_token_id, target_position_usdc, target_hedge_ratio. Research-view emissions follow feature.poly_research.<view>.complete. Metrics are still mostly noopMetrics in candidate-a bootstrap; do not assume Prometheus counters exist.
Which skill to load
| If you're doing… | Load |
|---|
Mirror pipeline, coordinator, wallet-watch, poly_copy_trade_* tables, v0 caps, poll cadence, shared-poller, Phase-4 streaming prep | poly-copy-trading |
| CLOB order placement, Data-API reads, fill-id semantics, EOA-vs-Safe-proxy gotchas, target-wallet screening / ranking research | poly-market-data |
Per-tenant /api/v1/poly/wallet/connect, Privy provisioning, poly_wallet_connections, CTF + USDC.e approvals, AEAD at rest, CustodialConsent, validating deploy_verified | poly-auth-wallets |
Research views, dashboard slices, P/L curves, histograms, comparison panels, SQL-vs-V8 aggregation, OOM diagnosis on poly_trader_fills / poly_trader_position_snapshots reads, backfill | data-research |
Load multiple if you're crossing domains (e.g., a research view that drives a target-ranking change is data-research + poly-copy-trading). Each specialty skill is self-contained; there is no "base" you have to load first.
Canonical references (cross-cutting)
Specs (as-built):
Current design/research pointers:
Guides:
Operational data tables (where research / data-science work lands):
| Table | Owner / writer | Coverage caveats |
|---|
poly_trader_fills | wallet-watch + spike.5024 historical walker | Full Polymarket history for tracked wallets after spike.5024 (RN1, swisstony walked from Apr) |
poly_trader_position_snapshots | wallet-analysis-service snapshot writer | Started writing 2026-05-03; pre-May-3 must be derived from fills (cumsum) for backfill |
poly_trader_current_positions | dashboard refresh path | Live, refreshed on read; not a historical record |
poly_trader_user_pnl_points | db-backed user-pnl read model (#1242) | Walked back via spike.5024 corpus |
poly_market_metadata | canonical Gamma persistence (#1265, #1270) | Started writing 2026-05-05; backfill via Gamma /markets/{conditionId} per condition |
poly_market_outcomes | runMarketOutcomeTick — condition-iterating writer (cp3, #1247) | Started writing 2026-05-05; reuse forward-fill loop with one-shot driver over conditions |
poly_market_price_history | cp7 db mirror (#1251) | Started writing 2026-05-05; backfill via CLOB /price-history?market={tokenId} |
poly_copy_trade_{targets,fills,decisions,attribution} | mirror coordinator | See poly-copy-trading for invariants + RLS |
poly_redeem_jobs | redeem worker (Capability B, #1242) | event-driven; cleared by completion |
poly_wallet_{connections,grants} | per-tenant onboarding | See poly-auth-wallets |
Project charter + work items:
The markdown work-item corpus was retired on 2026-04-25 (PR #1241). Items now live in Doltgres and are read via the operator API:
- proj.poly-copy-trading — full roadmap, open bugs, constraints (still markdown)
- Active poly items:
GET https://cognidao.org/api/v1/work/items?node=poly&statuses=needs_implement,needs_design,in_review
- Specific item:
GET https://cognidao.org/api/v1/work/items/{id} (e.g. task.5012, task.0322, bug.5012, spike.5024)
Charter still references ../items/*.md paths — those links are stale; use the API or follow links from the operator dashboard.
Anti-patterns that bite everywhere (regardless of specialty)
- Placing a test trade from a wallet you control and calling it "mirror validation." The mirror copies the TARGET. If the target didn't trade, the mirror has nothing to copy. True of shared operator, true of your own per-tenant wallet, true of raw-PK test wallets.
- Smuggling P4 (streaming / ranking) work into a v0 or v1 task. P4 is tracked in task.0322. Scope discipline matters here because the fill_id shape is frozen (
data-api:…) and mixing schemes corrupts the idempotency layer.
kubectl set env for long-lived config. Argo reverts on next sync. Secrets go through scripts/setup/setup-secrets.ts → candidate-flight-infra; config goes into the kustomize overlay.- Re-setting GH env secrets without checking
gh secret list --env candidate-a first. Rotates tokens out from under live flights.
- Trusting the Polymarket UI profile for EOA-direct wallets. The
/profile/<addr> page redirects to an empty Safe-proxy. Use Data-API /positions / /trades or Polygonscan. See poly-market-data for the full ground-truth order.
Observability backstop (MCP-down fallback)
grafana MCP is flaky. When it's down, use scripts/loki-query.sh — accepts raw LogQL, hits Grafana Cloud via service-account token, auto-sources .env.canary / .env.local. Same LogQL syntax as the MCP. Used to flip deploy_verified on task.0318 on 2026-04-22.
Cross-cutting enforcement
Rules that apply regardless of which specialty you're in:
- Never use raw PKs in production code paths.
scripts/experiments/ only. Production signs via Privy HSM (shared or per-user).
- Never skip
INSERT_BEFORE_PLACE in the coordinator — at-most-once correctness gate.
fill_id shape is frozen at data-api:<tx>:<asset>:<side>:<ts>. P4 will add clob-ws:…. Never mix schemes within one fill.- Idempotency is always
keccak256(target_id + ':' + fill_id) → client_order_id. No alternatives.
deploy_verified: true requires the full validation recipe, not just pnpm check. See poly-auth-wallets for the per-tenant provisioning recipe.
