12 — Roadmap¶

Six phases. Each has exit criteria rather than a date, because a phase that ships without meeting its criteria pushes the cost into the next one at interest. Durations are estimates for a small team and should be read as sequencing, not commitments.

The ordering principle: build the things that are hard to retrofit first. Point-in-time correctness, the compliance gate, and the audit manifest cannot be added later without rewriting everything above them. Agents and UI polish can.

Phase 0 — Foundations¶

≈ 4–6 weeks

The unglamorous phase that determines whether the rest is trustworthy.

Repository structure, dependency-direction enforcement, CI
Domain model: instruments, prices, fundamentals, portfolios, orders — with Decimal money and the bitemporal schema from 03 §3
Point-in-time feature store with the mandatory as_of interface
Ingestion for the Tier A sources: EDGAR XBRL, FRED, exchange calendars, corporate actions
Data validation and quality monitoring
The point-in-time audit harness, running in CI
Docker Compose profiles for solo and home-server

Exit criteria - Five years of daily bars, fundamentals, and corporate actions ingested for a 500-instrument universe - Point-in-time audit passes: no computation reads data with available_at beyond the decision time - Corporate action integrity check passes — every price gap beyond threshold has a matching action - Ingestion is idempotent: replaying a month produces byte-identical state

Phase 1 — Compliance & paper trading core¶

≈ 6–8 weeks

The two things that make this product what it is, before any AI.

Shariah rule pack engine with all four shipped methodologies plus custom
Business activity classification, ratio screens, impure income, purification
Compliance verdict history and drift monitoring
Paper trading engine: order state machine, fill simulation with spread and impact, participation caps, cost model
Corporate action processing in the ledger
Portfolio analytics and performance attribution
Risk engine: sizing, exposure limits, loss limits, circuit breakers
REST API surface for all of the above

Exit criteria - Compliance engine achieves ≥ 98% agreement with published index constituency on a labelled historical universe, with every disagreement documented - Ledger property tests pass: equity conservation, no negative positions, hash-chain integrity - A full year of simulated trading runs without a ledger discrepancy - Fill engine validated against a sample of real historical executions where available - No code path exists to a real broker — verified by test

Phase 2 — Agent system¶

≈ 8–10 weeks

Model gateway with local/cloud routing, redaction enforcement, budget accounting
Six Band 1 analyst agents with the Signal contract and evidence validation
Quarantine boundary and the red-team suite
Document corpus, chunking, hybrid time-filtered retrieval
Aggregator with cold-start fixed weights; calibration infrastructure in place but honestly labelled pre-calibration
Supervisor with explanation generation, faithfulness verification, and categorised veto
Band 2 agents: Risk Manager, Portfolio Manager, Execution Planner
LangGraph orchestration with checkpointing, streaming, and the full audit manifest
Agent eval harness with golden sets

Exit criteria - End-to-end recommendation produced from candidate to sized order, fully reproducible from its manifest - 100% of numeric claims in generated explanations resolve to stored evidence - Red-team suite passes with zero instances of ingested content influencing a score or a tool call - Full pipeline completes within the latency and cost budget on the reference profile - The system runs for seven consecutive days with all cloud providers disabled

Phase 3 — Web application & backtesting¶

≈ 10–12 weeks

React SPA: all five sections, generated API client, served as a static bundle by the API
The recommendation detail view — the "Why?" screen and its rejected-candidate counterpart
Paper trading flow with risk preview and persistent PAPER marking
Portfolio, performance, and risk screens with the plain-language risk translations
Conversational assistant with grounded citations and redaction banners
Backtesting engine: walk-forward, purged K-fold, combinatorial paths, Deflated Sharpe
In-app backtesting with constrained parameters and honest reporting
Live agent-run view driven by the SSE trace
PWA packaging: installability and web push for critical alerts
Onboarding, notifications, accessibility pass

Exit criteria - Backtest reproducibility test passes in CI from a stored manifest - All bias guards demonstrated by a deliberately-broken test strategy that the guards catch - WCAG AA verified; full keyboard navigation and screen reader support including chart summaries - Responsive layout verified down to a phone browser at single-column width - A user unfamiliar with the system can complete onboarding and understand a recommendation without assistance - Client functions fully against a local-only backend

Phase 4 — Learning, hardening, and expansion¶

≈ 8–10 weeks

Outcome recording and resolution across all recommendation types
Calibration pipeline; reliability diagrams and Brier decomposition exposed in-app
Aggregator retraining with gated promotion and shadow mode
Case memory retrieval
Failure taxonomy with automated categorisation and review workflow
Universe expansion beyond the initial market; multi-currency and FX handling
Sukuk and screened-ETF support with look-through
Security hardening: egress allowlist, encrypted storage, audit log, data-flow view
Performance optimisation; Rust extraction of hot paths only if profiling requires it

Exit criteria - Sufficient resolved recommendations for meaningful calibration, with the reliability diagram shown honestly whatever it says - Calibration target met, or the gap reported and confidence capped accordingly - Security review completed; red-team and dependency scanning clean - Twelve months of continuous operation without manual intervention

Phase 5: Live trading (gated, optional)¶

No date. Entered only if Phase 4 exit criteria are met and the user chooses it.

This phase is optional by design. A user who never enables it should have a complete product.

Broker adapter behind the existing interface — the first time this code is written
Enablement ceremony: minimum paper track record, risk acknowledgement, passkey assertion, cooling-off period
The three modes: recommend-only, recommend-and-approve, automated
Adapter-layer hard caps independent of the risk engine
Credential kill switch
Reconciliation between expected and actual fills, with divergence alerting
Live-vs-paper divergence monitoring — the honest test of whether the fill model was right

Entry criteria (all required) - ≥ 12 months of paper trading under the current model versions - Calibration verified: confidence buckets resolve within tolerance - Paper performance clears the naive compliant benchmark after costs - Zero unresolved correctness defects in ledger, compliance, or risk - Explicit user enablement through the full ceremony

Exit criteria - Fill divergence between live and modelled execution within tolerance - Kill switch verified to revoke credentials, not merely stop sending - Every hard cap independently tested at the adapter layer

Phase 6 — Ongoing¶

Continuous

Research and refinement with no fixed endpoint: additional agents where marginal contribution justifies them, feature research, rule pack additions as methodologies are reviewed, model upgrades through the gated promotion process, and universe expansion.

Crypto rule packs are revisited here if and only if a methodology with clear provenance can be written; shipping a guess remains worse than shipping nothing.

Sequencing rationale¶

Why compliance before AI. The compliance gate eliminates most of the universe before any inference is spent. Building it first makes every subsequent phase cheaper, and it is the constraint that shapes the trading engine's capabilities — retrofitting "no shorting, no margin, no interest" into a built engine means rewriting the ledger.

Why paper trading before agents. The simulator is the measuring instrument. Building the thing to be measured before the instrument means having no way to know whether it works.

Why calibration is Phase 4, not Phase 2. Calibration requires resolved outcomes, which require elapsed time. There is no way to compress this, and pretending otherwise by calibrating on backtested outcomes would produce a number that describes the backtest rather than the system.

Why live trading is last and optional. It is the only irreversible capability in the product. Everything before it can be wrong and cost nothing but time.

Risks to the plan¶

Risk	Mitigation
Data licensing limits the universe	Adapter abstraction keeps providers swappable; Tier A free sources cover the US market fully
Local model quality insufficient for tier-3 synthesis	Cloud path available; degradation is disclosed on output rather than hidden
Compliance validation reveals systematic disagreement with published indices	Expected and informative — disagreements usually reveal denominator or timing conventions; documented rather than tuned away
Calibration never converges	Report it. A system that says "my confidence numbers are not yet meaningful" is more valuable than one that pretends
Scope expansion into multi-user or commercial use	Explicitly out of scope in 00 §4; the regulatory posture would differ fundamentally