islandflow/docs/implementation

Implementation Phase Plans

This directory is the active planning layer for the synthetic market-data and smart-money/smart-flow architecture work.

The architecture reviews in docs/plans/ and research reports in docs/research-docs/ are background guidance. Future implementation work should use the current phase document and matching Beads issue as the active scope. If a phase document and an older architecture review or research report disagree, pause and update the phase document or Beads issue before writing code.

Document Precedence

Use this precedence order when planning or implementing phase work:

1. Current Beads issue
2. Referenced phase document under docs/implementation/
3. Architecture plan under docs/plans/
4. Research report under docs/research-docs/

This repository uses docs/research-docs/ for research reports; docs/research/ is not present.

Research reports provide rationale and useful constraints. They do not add active implementation scope unless that scope is explicitly pulled into a phase document and Beads issue.

Source Plans

• docs/plans/synthetic-market-data-architecture-review.md
• docs/plans/smart-flow-architecture-review.md

Planning Rules

• Prefer small, reviewable PRs.
• Do not implement an entire architecture plan at once.
• Use Beads issues for execution tracking and dependency management.
• Keep durable architecture and phase detail in these docs, not in long Beads descriptions.
• Synthetic data must emit canonical market event types, not synthetic-only pipeline event types.
• Synthetic labels must remain separate from emitted market events.
• Smart-flow logic must distinguish facts, evidence, hypotheses, confidence, and abstention.
• Historical calibration is future work, not an MVP dependency.
• Early synthetic tests must not require Docker, ClickHouse, NATS, or Redis.
• Synthetic foundations should come before demos, UI controls, or live service work.

Beads Map

Stream	Epic	Roadmap
Synthetic market data	islandflow-259 - Plan synthetic market-data implementation phases	docs/implementation/synthetic-market-data/00-roadmap.md
Smart money / smart flow	islandflow-zxh - Plan smart-money to smart-flow implementation phases	docs/implementation/smart-money/00-roadmap.md

Dependency Order

This is the intended MVP ordering. Future calibration phases sit after the MVP chain and should not block it.

Order	Phase	Beads issue	Blocks next because
1A	Synthetic deterministic spine	islandflow-259.1	Establishes seeded raw event generation and provenance assumptions for later synthetic work.
1B	Smart-flow contracts and vocabulary	islandflow-zxh.1	Can safely run in parallel with synthetic phase 01; defines evidence/hypothesis language before scoring work.
2	Synthetic manifests, fixtures, and CLI	islandflow-259.2	Evidence clustering needs deterministic fixtures before broad behavior changes.
3	Smart-flow evidence clustering and features	islandflow-zxh.2	Scenario labels need the evidence vocabulary they are expected to exercise.
4	Synthetic scenarios, labels, and expected outputs	islandflow-259.3	Hypothesis scoring needs labeled positive, negative, and abstention cases.
5	Smart-flow hypothesis scoring and abstention	islandflow-zxh.3	Synthetic replay integration should validate the derived hypothesis pipeline.
6	Synthetic replay integration	islandflow-259.4	Smart-flow golden tests need replayable synthetic runs.
7	Smart-flow replay evaluation and golden tests	islandflow-zxh.4	Demos should wait until replay proves the semantics.
8	Synthetic demo and load profiles	islandflow-259.5	API/UI explainability should show stable, named, deterministic runs.
9	Smart-flow API/UI explainability	islandflow-zxh.5	This is the final MVP presentation layer after the evidence pipeline is validated.

Future Work

Future phase	Beads issue	Notes
Synthetic historical calibration	islandflow-259.6	Depends on synthetic phase 05, but is not required for MVP.
Smart-flow calibration	islandflow-zxh.6	Depends on smart-flow phase 05 and synthetic future calibration, but is not required for MVP.

Existing Related Issue

islandflow-9dz already tracks tuning synthetic smart-money scenario coverage. It is narrower than these phase plans and was already in progress before this split. Treat it as related context for docs/implementation/synthetic-market-data/03-scenarios-labels-expected-outputs.md, not as the phase-level tracker.