docs: add ADR-0012 (confluence signal engine) + glossary terms (M22 slice 12)

ADR-0012 documents the 34-slot confluence signal engine architecture: slot
catalog, redundancy-aware rack evaluation, CandleProvider seam, closed-loop
signal history, and picture-change alert producer. CONTEXT.md gains a new
'Confluence Signal Engine (M22)' glossary section.

CONTEXT.md

@@ -152,6 +152,28 @@ Screener output policy (both modules): symbol + "why matched" + one-tap "open in
 
 **Portfolio Impact Commentary** — LLM-generated (Druckenmiller lens), two-horizon: short-term reaction risk (per-event, per-correlation-cluster, with historical averages + sample size + disclaimer, never a forecast) and long-term structural read (regime-shift framing). Cites M18 regime + the user's actual holdings. Always on (matches Analyst Voice "always on" decision).
 
+## Confluence Signal Engine (M22)
+
+**Confluence Signal Engine** — The multi-axis evidence aggregator that produces a per-symbol "picture quality" (strong/moderate/weak-bullish, mixed, weak/moderate/strong-bearish, sparse) from34 independently-evaluable slots across 6 families: technical (15), institutional (5), macro (5), seasonal (5), flows (3), sentiment (1). ADR-0007: describes the picture, never recommends action. ADR-0012.
+
+**Slot** — A named, independently-evaluable check whose firing state contributes bullish or bearish evidence to a confluence rack. Each slot has a `SlotBody` (bull / bear / exit), a `SlotFamily`, a `SlotGranularity` (1d / 1wk), and an ADR-safe `explain` note (evidence sentence, never a directive). The 34-slot catalog is defined in `confluenceSlots.ts`.
+
+**Rack** — A named subset of the 34 slots that evaluates a symbol's confluence. Can be a system preset (Full Confluence, Technical Momentum, Macro+Flows+Sentiment) or user-created. A rack evaluation produces the redundancy-discounted evidence totals and picture quality label.
+
+**Redundancy Group** — A set of slots that measure the same underlying condition (e.g. goldenCross + trendAlignment + pullbackToEMA21 all measure trend state). Evidence within a group decays geometrically (1 + 0.5 + 0.25 ...) so correlated signals count once, not triple. Defined in `confluenceLibrary.ts`.
+
+**Picture Quality** — The evidence-based label for a symbol's confluence: strong/moderate/weak-bullish, mixed, weak/moderate/strong-bearish, sparse. Labeled from redundancy-discounted evidence totals using direction ratio (0.6) and magnitude thresholds (strong ≥ 4.0, moderate ≥ 2.0, sparse < 1.0 total evidence).
+
+**CandleProvider** — The seam that resolves a symbol's candles per-granularity (1d/1wk) from the cache, with a realtime fold-in of the freshest live quote. Used by confluence evaluators instead of `cache.get` inline so a future realtime/replay source can slot in without touching slot logic. `candleProvider.ts`.
+
+**Signal History** — The closed-loop log: every slot fire is recorded with the as-of date, rack, and picture quality. A resolver later checks whether price moved the expected direction over 4 weeks (bull → up, bear/exit → down). Verdicts: `real` (confirmed), `false_alarm`, or `deferred` (not enough forward bars). Per-slot reliability weights (0.5–1.25) allow the rack to self-tune.
+
+**Reliability Weight** — A 0.5–1.25 multiplier applied to a slot's evidence based on its historical follow-through: ≥8 resolved fires at ≥90% hit rate → 1.25×; <2 resolved or ≤50% → 0.5×; thin sample → 0.75×. The rack can multiply per-slot evidence by this to self-tune.
+
+**Confluence Change** — A detected shift in picture quality tier or net evidence (≥ 0.35 shift). Driven by the `confluence_change` alert producer. Throttled to 5/hr. ADR-0007 framing: "the picture has changed," never "act now."
+
+**Confluence Universe** — The 15 research symbols + SPY benchmark that the confluence engine tracks: PLTR, NVDA, AMD, AAPL, MSFT, SMH, XOM, JPM, UNH, COST, AMZN, CAT, LMT, LIN, NEE. Pinned into the demand set on startup.
+
 **Regime History** — Timeline of regime classifications over time; cross-references Rotation Signal History. Pedagogy for "did we detect the shift correctly" — beginner learns which classifier calls were early vs whipsawed.
 
 ## LLM Data Provenance (ADR-0006)

docs/adr/0012-confluence-signal-engine.md

@@ -0,0 +1,97 @@
+# ADR-0012: Confluence Signal Engine (M22)
+
+Date: 2026-08-10  
+Status: Accepted
+
+## Context
+
+Investor Flow evaluates entry/exit quality for a symbol by combining multiple
+evidence axes (technical, institutional, macro, seasonal, flows, sentiment).
+The existing codebase had per-indicator helpers (RSI, MACD, moving averages,
+volume-by-price, rotation, seasonality) but no unified layer that combined
+them into a single, per-symbol, per-date assessment. Users saw individual
+indicators but not the synthesized picture.
+
+The product needs an evidence-based confluence layer that:
+- Aggregates multi-axis signals into a single "picture quality" for a symbol
+- Discounts redundant signals (e.g. golden cross + trend alignment both measure
+  the same thing) so correlated evidence isn't double-counted
+- Produces an ADR-0007-safe output: evidence descriptions ("strong bullish
+  picture"), never buy/sell directives
+- Supports a closed loop: slot fires are logged and later resolved to
+  confirmed/false-alarm by measuring whether price followed through
+
+## Decision
+
+Build a **34-slot Confluence Signal Engine** as a first-class module
+(`app/server/src/confluence/`).
+
+### 1. Slot catalog (34 slots, 6 families)
+
+Each slot is an independently-evaluable check whose firing state contributes
+bullish or bearish evidence. Families: technical (15), institutional (5),
+macro (5), seasonal (5), flows (3), sentiment (1). Slots carry an ADR-safe
+`explain` note (evidence sentence, never a directive). `SlotBody`: bull / bear
+/ exit (exit = bear evidence for an existing position).
+
+### 2. Redundancy-aware rack evaluation
+
+Slots are bucketed into redundancy groups (e.g. goldenCross +
+trendAlignment + pullbackToEMA21). Within each group, evidence decays
+geometrically (1 + 0.5 + 0.25 ...) so correlated signals count once, not
+three times. The rack then labels the picture using evidence totals:
+
+- `MIN_TOTAL_EVIDENCE = 1.0` (below → sparse)
+- `DIRECTION_RATIO = 0.6` (bull/totals must reach this for bullish label)
+- `STRONG_EVIDENCE = 4.0`, `MODERATE_EVIDENCE = 2.0` (magnitude thresholds)
+
+Quality labels: strong/moderate/weak-bullish, mixed, weak/moderate/strong-
+bearish, sparse.
+
+### 3. CandleProvider seam (data abstraction)
+
+Confluence evaluators resolve candles through a `CandleProvider` interface,
+not `cache.get` inline. The cache-backed implementation folds in the freshest
+live quote as a partial daily bar so mid-session evaluations see the current
+price, not just the last EOD close. Weekly slots (50/200 cross, trend
+alignment) use the weekly cache key. This seam is pluggable for future
+replay/realtime sources.
+
+### 4. Closed-loop signal history
+
+Every slot fire is logged to `confluence_signal_history` with the as-of date,
+rack, and picture quality at the time. A resolver later checks whether price
+moved the expected direction over 4 weeks (bull slots → price up, bear/exit
+slots → price down). A small dead-band (0.5%) treats flat outcomes as
+unresolved rather than false alarms. Per-slot reliability weights (0.5–1.25)
+allow the rack to self-tune over time.
+
+### 5. Picture-change alert producer
+
+The `confluence_change` alert type fires when the picture quality tier
+changes (improved / deteriorated) or net evidence shifts beyond 0.35.
+Throttled to 5 per hour per type. ADR-0007 framing: "the picture has
+changed," never "act now."
+
+### 6. COT data adapter
+
+The CFTC Traders-in-Financial-Futures report (leveraged-funds long/short +
+open interest) is fetched from CFTC's annual zip files and parsed. The
+`cotPositioning` slot consumes this data. Registered under the `cftc`
+vendor family with 1.5s min-interval pacing.
+
+## Consequences
+
+- The tRPC `confluence.*` router exposes slots, racks, evaluation, backtest,
+  scorecard, and saveRack. The frontend `/confluence` page shows picture
+  quality, per-slot evidence, and reliability scorecard.
+- Three system rack presets are seeded on startup: Full Confluence (all 34),
+  Technical Momentum (15), Macro + Flows + Sentiment (14).
+- The 15-symbol confluence universe (PLTR, NVDA, AMD, AAPL, MSFT, SMH, XOM,
+  JPM, UNH, COST, AMZN, CAT, LMT, LIN, NEE) + SPY benchmark are pinned
+  into the demand set on startup.
+- No advisory output is produced. All picture-quality labels describe
+  evidence; they never recommend action.
+- The closed loop is not self-executing: the `confluence.eval` procedure
+  must be triggered to produce evaluations. The backtest procedure is
+  read-only and query-driven. Future work can schedule periodic evaluation.