ohld · Oct 31, 2026 · Oct 31, 2026 · Oct 31, 2026 · Oct 31, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -26,6 +26,12 @@
 - User reactions are persisted through `create_user_meme_reaction` / `update_user_meme_reaction` (see [`src/recommendations/service.py`](src/recommendations/service.py)). These records drive stats aggregation and recommendation eligibility.
 - Share attribution: deep links `s_{user_id}_{meme_id}` in `user_deep_link_log` — see `CONTEXT.md` **Share Attribution**. Growth thesis and measurement plan: [`docs/growth/virality-loop.md`](docs/growth/virality-loop.md).
 
+## Experiments
+- Experiments live in [`experiments/`](experiments/), one file each with flat front matter (id, status, check_on, result, learning, readout, ...).
+- Before designing an experiment, read [`experiments/README.md`](experiments/README.md): open checks plus every decided result and learning.
+- When starting or closing one, edit its file, then run `python scripts/experiments.py index` and commit the README (CI fails if it is stale).
+- `python scripts/experiments.py due` lists checks that are due; `readout <id>` prints the read-only SQL command for `$ANALYST_DATABASE_URL`.
+
 ## Operational notes
 - Manual upload review happens entirely inside the designated Telegram upload review chat. Keep communications and escalations there for traceability.
 - Weekly maintenance (Prefect flow health checks, data hygiene jobs, etc.) runs through Prefect deployment definitions. Use Prefect CLI to trigger flows during scheduled operations.

diff --git a/SPEC.md b/SPEC.md
@@ -56,7 +56,7 @@ Living entries (short list):
 | [specs/moderator-community-loop.md](specs/moderator-community-loop.md) | Source voting |
 | [docs/growth/virality-loop.md](docs/growth/virality-loop.md) | Growth thesis |
 
-Finished experiment write-ups: [experiments/completed/](experiments/completed/).
+Experiments (running and decided, one file each): [experiments/README.md](experiments/README.md).
 
 ## Invariants
 

diff --git a/TODOS.md b/TODOS.md
@@ -1,21 +1,21 @@
 # TODOS
 
 > Living backlog only. Completed items live in git history and dated experiment
-> write-ups under `experiments/completed/`.
+> write-ups in [`experiments/`](experiments/README.md).
 > Last cleaned: 2026-06 (Wave A hygiene).
 
 **Product compass:** [docs/growth/virality-loop.md](docs/growth/virality-loop.md)
 
 ## P1 — Growth & feed measurement
 
 ### ~~Virality score for ranking~~ — viral_shares_blender_v1 KILLED 2026-10-30
-**What:** Engine `viral_shares` + mature blend A/B (`viral_shares_blender_v1`). See `experiments/completed/2026-08-09-viral-shares-blender-v1.md`.
+**What:** Engine `viral_shares` + mature blend A/B (`viral_shares_blender_v1`). See `experiments/2026-08-09-viral-shares-blender-v1.md`.
 **Closed:** clickers/1k 0.031 control vs 0.025 treatment. Enrollment stopped, all users on control.
-**Rules + all open hypotheses:** [`docs/growth/HYPOTHESES.md`](docs/growth/HYPOTHESES.md).
+**All experiments and learnings:** [`experiments/README.md`](experiments/README.md).
 
 ### Cold-start first-session quality floors — SHIPPING
 **What:** explore raw-LR ≥0.50 / n≥25; CS3 blend uses best_uploaded + text_light (no like_spread).
-**Check:** H5 in `experiments/HYPOTHESES.md` — smoke 2026-08-12, primary 2026-08-16.
+**Check:** `experiments/2026-08-09-cold-start-floors.md` (H5).
 
 ### Broadcast HQ meme pick — SHIPPING
 **What:** retention pushes pick affinity×LR meme (`broadcast_reengagement_hq`) vs queue fallback.

diff --git a/docs/analyst/README.md b/docs/analyst/README.md
@@ -17,11 +17,9 @@ These queries and reports support product-health monitoring and experiment analy
 - `docs/analyst/dwell-feed-vs-broadcast.sql` — `sec_to_react` percentiles: like vs skip × feed vs broadcast; dwell buckets; demote inventory risk.
 - `docs/analyst/source-affinity-demote-guardrails.sql` — post-deploy volume / LR checks for soft-demote (#340).
 - `docs/analyst/broadcast-reengagement.sql` — retention push HQ vs queue fallback vs feed.
-- Living decision calendar (which experiments are live and which SQL each uses): [`docs/growth/HYPOTHESES.md`](../growth/HYPOTHESES.md). SQL for killed experiments is deleted; recover it from version control history if needed.
+- Experiment ledger (open experiments with check dates, decided ones with result + learning): [`experiments/README.md`](../../experiments/README.md). `python scripts/experiments.py due` lists checks that are due; `readout <id>` prints the SQL command. SQL for killed experiments is deleted; recover it from version control history if needed.
 - `docs/analyst/crossposting.sql` — reusable read-only queries for Telegram channel views/forwards, 24h labels, and pre-posting share signals.
 - `specs/crossposting-share-optimization-2026-05-18.md` — current compact crossposting readout and next experiment gate.
-- `experiments/active/` — Currently running experiments to monitor
-- `experiments/completed/` — Historical experiments for context
 
 ## Database Schema Reference
 Full table definitions: `src/database.py`
@@ -77,12 +75,14 @@ No hardcoded engine list or expected LRs here; they drift. Sources of truth:
 - **Prefect**: Pipeline health (parser → ETL → final_pipeline)
 
 ## North Star Metric
-Defined once in [`SPEC.md`](../../SPEC.md) (session length + organic growth via shares). The experiment ship bar (funnel + k-factor, with session length and block rate as guardrails) is in [`docs/growth/HYPOTHESES.md`](../growth/HYPOTHESES.md). Do not restate either here.
+Defined once in [`SPEC.md`](../../SPEC.md) (session length + organic growth via shares). The experiment ship bar (funnel + k-factor, with session length and block rate as guardrails) is in [`experiments/README.md`](../../experiments/README.md). Do not restate either here.
 
 Operational health signals:
 
 **Describe Memes throughput**: `described_24h` — memes described by the OpenRouter Vision flow in the last 24h. Expected >0. Zero means the circuit breaker has paused the flow. See "DESCRIBE MEMES THROUGHPUT" section in metrics.sql.
 
 **Chat Agent metrics**: agent_calls_24h, active_chats_24h, avg_response_ms, token_cost_usd, chat meme like rate. See "CHAT AGENT" section in metrics.sql.
 
-See `experiments/README.md` for report format and `docs/analyst/metrics.sql` for the actual queries.
+Healthy product snapshot (rough, not ship gates): new_memes_24h > 100, ok_pct ~90–96%, active reactors 24h not collapsing vs prior week, multi-engine mix still present.
+
+Queries: `docs/analyst/metrics.sql`.
diff --git a/docs/analyst/broadcast-holdout-v1.sql b/docs/analyst/broadcast-holdout-v1.sql
@@ -1,6 +1,6 @@
 -- Readout: broadcast_cadence_holdout_v1_<step> (15m/24h/1w/2w/4w) and
 -- monthly_reminder_v1, treated vs holdout. Read-only, one SELECT.
--- Experiment note: experiments/active/2026-10-30-broadcast-cadence-holdout.md
+-- Experiment note: experiments/2026-10-30-broadcast-cadence-holdout.md
 --
 -- Assignment = first time the user was selected by that step (intent-to-treat;
 -- holdout users were selected but not pushed). Steps are randomized

diff --git a/docs/analyst/broadcast-reengagement.sql b/docs/analyst/broadcast-reengagement.sql
@@ -8,7 +8,7 @@
 -- Compare to in-session feed engines (recommended_by NOT LIKE 'broadcast%').
 -- Primary: reactivation (react within 1h), LR, sec_to_react p50.
 --
--- See experiments/HYPOTHESES.md H3 / H5.
+-- See experiments/2026-08-09-broadcast-hq-pick.md (H3b) and experiments/README.md.
 
 \set ON_ERROR_STOP on
 

diff --git a/docs/analyst/crossposting-content-tags-gates.py b/docs/analyst/crossposting-content-tags-gates.py
@@ -1,6 +1,6 @@
 """Gates for the crosspost content-tags hypothesis (read-only).
 
-Experiment: experiments/active/2026-10-31-crosspost-content-tags.md
+Experiment: experiments/2026-10-31-crosspost-content-tags.md
 Research:   docs/analyst/research/2026-10-30-forward-drivers/
 
 Usage (analyst machine, needs pandas + statsmodels + scikit-learn):

diff --git a/docs/analyst/crossposting-content-tags-shadow.sql b/docs/analyst/crossposting-content-tags-shadow.sql
@@ -1,4 +1,4 @@
--- Crosspost content-tags shadow readout (experiments/active/2026-10-31-crosspost-content-tags.md).
+-- Crosspost content-tags shadow readout (experiments/2026-10-31-crosspost-content-tags.md).
 -- One SELECT, one row per channel. Production pick is unchanged; v5c is log-only.
 --
 -- score_v5c = score_v5 * content_mult_v1, content_mult_v1 = 0.85 ^ (relatable + tweet_screenshot)

diff --git a/docs/analyst/crossposting-src-fwd-shadow.sql b/docs/analyst/crossposting-src-fwd-shadow.sql
@@ -1,5 +1,5 @@
 -- Crosspost source-forward-rate shadow readout
--- (experiments/active/2026-11-01-crosspost-src-forward-rate.md).
+-- (experiments/2026-11-01-crosspost-src-forward-rate.md).
 -- One SELECT, one row per channel. Production pick is unchanged; v5f is log-only.
 --
 -- score_v5f = score_v5 * (0.5 + src_fwd_pct), 1.0 multiplier when src_fwd_pct is NULL

diff --git a/docs/analyst/crossposting-v5-shadow.sql b/docs/analyst/crossposting-v5-shadow.sql
@@ -1,4 +1,4 @@
--- Crosspost v5 shadow readout (experiments/active/2026-10-30-crosspost-v5-shadow.md).
+-- Crosspost v5 shadow readout (experiments/2026-10-30-crosspost-v5-shadow.md).
 -- One SELECT, one row per channel. Production pick is unchanged; v5 is log-only.
 --
 -- zf = ln(1+forwards) - channel x MSK-week mean over posted image memes >= 48h old

diff --git a/docs/analyst/explore-budget-v1.sql b/docs/analyst/explore-budget-v1.sql
@@ -1,5 +1,5 @@
 -- explore_budget_v1 readout (one SELECT; read-only)
--- Experiment doc: experiments/active/2026-10-30-explore-budget.md
+-- Experiment doc: experiments/2026-10-30-explore-budget.md
 -- Rows: variant x segment (mod = moderator/admin, user = everyone else).
 -- Per-user means, feed sends only (recommended_by NOT LIKE 'broadcast%'),
 -- counted from each user's assigned_at.

diff --git a/docs/analyst/onboarding-funnel.sql b/docs/analyst/onboarding-funnel.sql
@@ -1,7 +1,7 @@
 -- Onboarding funnel + first-meme quality
 --
 -- Companion: docs/analyst/readouts/2026-09-07-onboarding-and-dormant-blast.md
--- Hypotheses: docs/growth/HYPOTHESES.md H9 / H10 / H11
+-- Experiments: experiments/2026-09-07-onboarding-first-tap.md (H9), -cold-start-fresh-viral.md (H10), -onboarding-skip-countdown.md (H11)
 --
 -- Growth bar for any onboarding change:
 --   1) less leaky: first-tap %, first-like %, reached-5

diff --git a/docs/analyst/research/2026-10-30-forward-drivers/README.md b/docs/analyst/research/2026-10-30-forward-drivers/README.md
@@ -7,7 +7,7 @@ Result: two traits predict **fewer** forwards: a relatable everyday joke and a t
 Threads screenshot. Each one costs about −0.1 zf. Political or news memes get **more**
 forwards (+0.19 zf), but only 57 posts have that label, so we log it and do not use it.
 
-Experiment: [`experiments/active/2026-10-31-crosspost-content-tags.md`](../../../../experiments/active/2026-10-31-crosspost-content-tags.md).
+Experiment: [`experiments/2026-10-31-crosspost-content-tags.md`](../../../../experiments/2026-10-31-crosspost-content-tags.md).
 
 ## Data and method
 

diff --git a/docs/broadcasts.md b/docs/broadcasts.md
@@ -51,7 +51,7 @@ Cadence steps require a real reaction near the step window (not just
 month 13:00 MSK) uses `send_meme_broadcast()` with
 `broadcast_id = monthly-reminder-YYYY-MM`, so a retry or manual re-run in the
 same month is deduped. Both carry holdouts logged in `experiment_assignment`;
-see `experiments/active/2026-10-30-broadcast-cadence-holdout.md`.
+see `experiments/2026-10-30-broadcast-cadence-holdout.md`.
 
 ### 3. Monitor