document research basis for phase plans

docs/implementation/smart-money/00-roadmap.md

@@ -2,6 +2,14 @@
 
 This roadmap breaks `docs/plans/smart-flow-architecture-review.md` into implementation-sized phases. The recommended direction is Option B: keep the working stack, but rebuild the domain pipeline around observations, evidence clusters, cautious hypotheses, confidence, alternatives, abstention, replay evaluation, and user-facing insight projections.
 
+## Source Documents
+
+- Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
+- Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+- Research architecture review copy: [`docs/research-docs/smart-flow-architecture-review.md`](../../research-docs/smart-flow-architecture-review.md)
+
+The research documents are background and rationale only. Scope comes from the Beads issue and the phase document.
+
 ## Core Constraints
 
 - Do not treat "smart money" as a canonical fact emitted by the system.

docs/implementation/smart-money/01-contracts-vocabulary.md

@@ -8,6 +8,23 @@ Introduce the domain vocabulary and contracts that distinguish observations, evi
 
 The current system has useful infrastructure but overconfident domain names. Before changing classifier behavior, the codebase needs the language to express what is observed, what is inferred, what is uncertain, and when the system should abstain.
 
+## Source documents
+
+- Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
+- Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+
+These documents are rationale, not added scope. This phase implements only vocabulary, contracts, versioning, and compatibility notes.
+
+## Research basis
+
+- The research direction is direct observation to inference to hypothesis, with preserved evidence and visible uncertainty.
+- "Smart money" should not be modeled as a canonical fact; user-facing insight should be a projection from evidence-backed hypotheses.
+- Confidence, conviction, alternatives, and abstention need separate language before behavior changes.
+
+## Deferred research ideas
+
+- Participant identity claims and research-grade calibration stay outside the vocabulary foundation.
+
 ## Dependencies on earlier phases
 
 - `islandflow-259.1` - Synthetic deterministic spine, so contract work can align with canonical raw event and provenance assumptions.

docs/implementation/smart-money/02-evidence-clustering-features.md

@@ -8,6 +8,23 @@ Make evidence extraction, eligibility, quote/context joins, clustering, and feat
 
 Contracts alone do not change behavior. This phase gives the system a clean evidence layer so later scoring can reason from auditable facts instead of a generic feature bag or overconfident classifier labels.
 
+## Source documents
+
+- Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
+- Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+
+These documents are rationale, not added scope. This phase implements only eligibility, evidence facts, clustering, and traceable features.
+
+## Research basis
+
+- Trade signing, quote context, sale conditions, stale quotes, wide markets, and event context all affect whether a print is usable evidence.
+- Evidence should preserve raw refs, eligibility decisions, quality signals, and negative context before any hypothesis is scored.
+- Ingest should normalize observations; signal policy belongs in explicit evidence/scoring stages.
+
+## Deferred research ideas
+
+- Full IV-surface modeling, broad news/FDA event feeds, and deep historical baselines can be added later when scoped.
+
 ## Dependencies on earlier phases
 
 - `islandflow-zxh.1` - Smart-flow contracts and vocabulary

docs/implementation/smart-money/03-hypothesis-scoring-abstention.md

@@ -8,6 +8,23 @@ Convert evidence clusters into cautious flow hypotheses with explicit score vect
 
 Scoring should wait until the system can represent evidence clearly and synthetic scenarios can describe expected positive, negative, and abstention cases. This phase is where the product stops acting like every signal is a confident "smart money" claim.
 
+## Source documents
+
+- Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
+- Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+
+These documents are rationale, not added scope. This phase implements only cautious hypothesis scoring, alternatives, penalties, and abstention.
+
+## Research basis
+
+- Premium concentration, sweep-like activity, IV movement, and equity confirmation support hypotheses only when evidence quality and context agree.
+- False positives from deep-ITM stock replacement, spreads/hedges, stale quotes, and event-driven flow need explicit penalties or abstention.
+- Confidence should reflect policy confidence in the evidence, not a claim of hidden participant identity.
+
+## Deferred research ideas
+
+- Empirical threshold tuning, historical calibration, and ML-based scoring stay future work until replay/golden validation exists.
+
 ## Dependencies on earlier phases
 
 - `islandflow-zxh.1` - Smart-flow contracts and vocabulary

docs/implementation/smart-money/04-replay-evaluation-golden-tests.md

@@ -8,6 +8,24 @@ Make deterministic replay and golden output comparison the acceptance gate for s
 
 Replay evaluation should come after synthetic replay can select stable runs and after hypothesis scoring has outputs worth validating. This phase turns architecture discipline into a repeatable test path.
 
+## Source documents
+
+- Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
+- Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+- Synthetic research report: [`docs/research-docs/synthetic-market-data-generation.md`](../../research-docs/synthetic-market-data-generation.md)
+
+These documents are rationale, not added scope. This phase implements only deterministic replay evaluation and compact golden tests.
+
+## Research basis
+
+- Replay is the acceptance gate for derived smart-flow outputs because evidence and hypotheses must be reproducible.
+- Validation must include positive cases, false positives, noisy contexts, and abstentions.
+- Tests should avoid lookahead bias and compare stable signatures instead of brittle full-payload dumps.
+
+## Deferred research ideas
+
+- Historical backtesting windows, empirical calibration datasets, and broad benchmark reports belong in later calibration work.
+
 ## Dependencies on earlier phases
 
 - `islandflow-zxh.1` - Smart-flow contracts and vocabulary

docs/implementation/smart-money/05-api-ui-explainability.md

@@ -8,6 +8,23 @@ Expose evidence-backed smart-flow outputs through API, websocket, and UI surface
 
 The presentation layer should wait until contracts, evidence, scoring, and replay evaluation are stable. Otherwise the UI will harden old overconfident language or teach users to trust unvalidated outputs.
 
+## Source documents
+
+- Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
+- Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+
+These documents are rationale, not added scope. This phase implements only API, websocket, and UI explainability surfaces for validated outputs.
+
+## Research basis
+
+- Users need to see evidence quality, confidence versus conviction, alternatives, and abstention instead of a single certainty label.
+- The research supports cautious smart-flow insight projections, not canonical "smart money" facts.
+- Why-not and penalty context are part of the product surface because false positives are central to the domain.
+
+## Deferred research ideas
+
+- Advanced explanatory analytics, learned confidence calibration, and broad catalyst intelligence should wait for future scoped work.
+
 ## Dependencies on earlier phases
 
 - `islandflow-zxh.1` - Smart-flow contracts and vocabulary

docs/implementation/smart-money/99-future-calibration.md

@@ -8,6 +8,23 @@ Plan future calibration of smart-flow confidence, policy thresholds, penalties,
 
 The architecture should leave room for calibration, but calibration should not block the MVP. The system first needs clean facts, evidence, hypotheses, and replayable evaluation before tuning can be meaningful.
 
+## Source documents
+
+- Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
+- Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+
+These documents are rationale, not added scope. This future phase is the place to turn research ideas into scoped calibration work after MVP.
+
+## Research basis
+
+- Historical validation should be time-of-day aware and avoid lookahead bias.
+- Baselines for "unusual" should account for ticker, tenor bucket, regime, and event-day exclusions.
+- Confidence, penalties, abstention, and alternatives need versioned policy outputs so calibration stays auditable.
+
+## Deferred research ideas
+
+- ML scoring, learned calibration, richer catalyst feeds, and large historical benchmark suites require separate future Beads scope.
+
 ## Dependencies on earlier phases
 
 - `islandflow-zxh.5` - Smart-flow API/UI explainability