Roadmap¶
The roadmap lives in roadmap/roadmap.yaml
and is mirrored on GitHub as milestones, epics and sub-issues. Tasks marked
parallel can be picked up independently; good first issue is a good place to start.
The Kanban board lives in the GitHub Project "Fairmark roadmap", created and filled by
scripts/setup_github_project.py.
Tasks are linked to their issues and, where one exists, to their specification. The state of
each task is copied from GitHub by scripts/roadmap.py sync, and a scheduled job reports any
difference with GitHub. The tables below are generated from roadmap/roadmap.yaml each time
the site is built.
| Milestone | Gate | Release | Done | Open |
|---|---|---|---|---|
| M0 · Foundations | A 'hello NPV' package on TestPyPI installs on Linux, macOS and Windows. | 0.1.0 | 22 | 2 |
| M1 · Numerical core | Golden harness green; NPV and IRR validated; property tests running. | 0.1.0 | 15 | 5 |
| M2 · Complete DCF | DCF passes every golden case provided by practitioners. | 0.1.0 | 14 | 7 |
| M3 · Agent layer and v0.1 release | An external user completes a DCF with Claude Code or Codex using only the README. | 0.1.0 | 13 | 9 |
| M4 · Traditional European methods | Golden cases green for every method. | 0.2.0 | 0 | 6 |
| M5 · Opt-in usage statistics | CI proves the payload carries no financial data; privacy notice reviewed by counsel. | 0.3.0 | 0 | 4 |
| M6 · v1.0 and real estate | Stable API with a published deprecation policy. | 1.0.0 | 0 | 9 |
M0 · Foundations¶
Gate: A 'hello NPV' package on TestPyPI installs on Linux, macOS and Windows.
| Epic | Task | Issue | Spec | Status |
|---|---|---|---|---|
| Repository and governance | Monorepo layout, LICENSE, NOTICE, README | #7 | Done | |
| Repository and governance | CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, GOVERNANCE | #8 | Done | |
| Repository and governance | ADR 0001–0005 | #9 | Done | |
| Repository and governance | Session protocol, naming conventions and dependency maintenance | #93 | Done | |
| Repository and governance | Commit scopes for every engine theme | #111 | Done | |
| Repository and governance | Roadmap as code: checked offline, synchronised with GitHub | #113 | Done | |
| Repository and governance | A pull request marks the task it closes as done in the roadmap | #119 | Done | |
| Repository and governance | Roadmap updates proposed from the maintainer's requests | #123 | Done | |
| Repository and governance | Session journal for 2026-11-07 | #132 | Done | |
| Repository and governance | Release notes and changelog on the site: undated draft, numerical changes name the method versions | #143 | Done | |
| Repository and governance | Commit scope for the loans theme | #157 | Done | |
| Repository and governance | Roadmap page generated at build time instead of committed | #159 | Done | |
| Repository and governance | Agents stop when an approved change reaches golden cases outside its scope | #173 | Done | |
| CI/CD | Rust pipeline: fmt, clippy, test, cargo-deny | #11 | Done | |
| CI/CD | Python pipeline: ruff, mypy, pytest on 3 OS | #12 | Done | |
| CI/CD | Wheel matrix with maturin-action, trusted publishing to PyPI and crates.io | #13 | Open | |
| CI/CD | pre-commit configuration | #14 | Done | |
| CI/CD | Deterministic checks: workflows (actionlint, zizmor), YAML validity, unused Rust dependencies, external links | #117 | Done | |
| CI/CD | Roadmap sync tolerates changes pending in open pull requests; Pages deploy waits for slow CDN purges | #134 | Done | |
| CI/CD | Roadmap sync treats issues closed by an open pull request as pending | #152 | Done | |
| CI/CD | Release preparation runs as a workflow that opens the release pull request | #142 | Done | |
| CI/CD | Release scripts validate versions as whole strings | #154 | Done | |
| Community infrastructure | Issue forms: bug, method request, numerical discrepancy | #16 | Done | |
| Community infrastructure | Labels, GitHub Project board, Discussions | #17 | Open |
M1 · Numerical core¶
Gate: Golden harness green; NPV and IRR validated; property tests running.
| Epic | Task | Issue | Spec | Status |
|---|---|---|---|---|
| Domain types | Money, Rate (annual vs per period), Period, Timeline with timing convention | #19 | Open | |
| Time value of money | Discount factors, NPV | #21 | Done | |
| Time value of money | XNPV / XIRR with day-count conventions | #22 | Done | |
| Time value of money | Annuities and growing perpetuities | #23 | Done | |
| Time value of money | Deterministic IRR solver | #24 | Done | |
| Time value of money | Time value foundations: dates, day counts, rates, XNPV, XIRR, MIRR, annuities | #95 | 0002 | Done |
| Time value of money | Draft spec for loans: payment, number of periods, future value and amortisation schedules | #135 | 0009 | Done |
| Time value of money | Loan instalment, number of instalments and future value | #136 | 0009 | Done |
| Time value of money | Amortisation schedules: French, fixed amortisation schedule, bullet, principal grace period | #137 | 0009 | Done |
| Time value of money | Full precision of present values at long horizons in tvm | #175 | Open | |
| Time value of money | Code review of the time value foundations for promotion to available | #176 | 0002 | Open |
| Explain and audit trail | Explain structure, JSON serialization | #26 | Done | |
| Explain and audit trail | Markdown and Excel (live formulas) rendering of explain | #27 | Open | |
| Errors and schema | Typed errors with stable codes and catalogue | #29 | Done | |
| Errors and schema | Schema versioning and changelog of schema changes | #30 | Done | |
| Errors and schema | Method trait per theme, single registry list, versioned input schemas | #103 | Done | |
| Errors and schema | Every error names the input field by its JSON pointer | #174 | Open | |
| Test harness | Golden YAML runner shared by Rust and Python | #32 | Done | |
| Test harness | Property tests with proptest (NPV at IRR = 0, monotonicity) | #33 | Done | |
| Test harness | Golden runners compare expected values exactly in Rust and Python | #148 | Done |
M2 · Complete DCF¶
Gate: DCF passes every golden case provided by practitioners.
| Epic | Task | Issue | Spec | Status |
|---|---|---|---|---|
| Financial statements input | Statutory income statement and balance sheet schema | #35 | 0005 | Open |
| Financial statements input | Reclassifications: functional / financial balance sheet, value-added P&L, net financial position | #36 | 0005 | Open |
| Free cash flows | Free cash flow build-up from EBIT, taxes, capex and working capital (dcf.free_cash_flows) | #38 | 0001 | Open |
| Free cash flows | Draft specs for cost of capital, multi-stage DCF and Italian valuation methods | #97 | 0001 | Done |
| Free cash flows | Parametric stages on the shared DCF engine (dcf.fcff v3) | #110 | 0001 | Done |
| Free cash flows | Approve SPEC-0001: free cash flows, stages, terminal value and equity bridge | #164 | 0001 | Done |
| Free cash flows | Free cash flow to equity on the shared DCF engine (dcf.fcfe) | #165 | 0001 | Open |
| Free cash flows | Nominal and real terms in the DCF: basis check and rate conversion | #166 | 0001 | Open |
| Cost of capital | CAPM, beta unlevering/relevering (Hamada, Harris-Pringle) | #40 | 0003 | Done |
| Cost of capital | WACC with size and specific risk premia as explicit inputs | #41 | 0003 | Done |
| Cost of capital | Cost of capital: CAPM, beta relevering, peer betas, cost of debt and WACC | #99 | 0003 | Done |
| Terminal value and equity bridge | Terminal value inside the DCF: technique and discounting time | #43 | 0001 | Open |
| Terminal value and equity bridge | From enterprise value to equity value: non-operating assets, debt-like items, non-controlling interests | #44 | 0001 | Open |
| Terminal value and equity bridge | Deterministic WACC × g sensitivity grid | #45 | 0008 | Done |
| Terminal value and equity bridge | Draft specs for terminal value methods and financial ratios with covenants | #101 | 0006 | Done |
| Terminal value and equity bridge | Terminal value building blocks tv.* (SPEC-0006) | #115 | 0006 | Done |
| Analysis: goal seek, sensitivity, scenarios, tornado | Draft spec for analysis: goal seek, sensitivity, scenarios, tornado | #106 | 0008 | Done |
| Analysis: goal seek, sensitivity, scenarios, tornado | Implement analysis.goal_seek with Brent's method on decimals | #108 | 0008 | Done |
| Analysis: goal seek, sensitivity, scenarios, tornado | Sensitivity tables, scenarios and tornado (SPEC-0008 R15 to R22) | #116 | 0008 | Done |
| Financial ratios and covenants | Ratios: profitability, capital structure, liquidity, working capital, debt service (SPEC-0007) | #114 | 0007 | Done |
| Financial ratios and covenants | Covenant tests on contractual definitions | #147 | 0007 | Done |
M3 · Agent layer and v0.1 release¶
Gate: An external user completes a DCF with Claude Code or Codex using only the README.
| Epic | Task | Issue | Spec | Status |
|---|---|---|---|---|
| Python SDK | PyO3 bindings, Pythonic API, Result object | #47 | Done | |
| Python SDK | Typed input models generated from JSON Schema | #48 | Open | |
| CLI | methods / schema / run / verify | #50 | Done | |
| CLI | Markdown output and batch mode | #51 | Open | |
| MCP and function calling | MCP server (stdio) generated from the registry | #53 | Done | |
| MCP and function calling | Function-calling tools for Anthropic and OpenAI with dispatcher | #54 | Done | |
| MCP and function calling | Gemini and LangChain adapters | #55 | Done | |
| Agent skills and docs | Agent Skill and AGENTS.md | #57 | Done | |
| Agent skills and docs | Docs site (MkDocs Material) with one methodology page per method | #58 | Done | |
| Agent skills and docs | Quickstarts for Claude Code, Codex, Python, n8n | #59 | Open | |
| Agent skills and docs | Public pages state only what exists; plans live in the generated roadmap | #121 | Done | |
| Agent skills and docs | Release notes and changelog pages always current | #127 | Done | |
| Agent skills and docs | Preview status defined, checked and exposed to agents | #149 | Open | |
| Agent skills and docs | Decision record: release notes for Italian readers | #161 | Done | |
| Agent skills and docs | Release notes in Italian, translated with each fragment (ADR 0011) | #163 | Open | |
| n8n node | Node/WASM build of the core | #61 | Open | |
| n8n node | Community node n8n-nodes-fairmark; check verified-node requirements | #62 | Open | |
| n8n node | Workflow template: financial statements PDF → valuation → report | #63 | Open | |
| Launch | Release v0.1.0, MCP registry listings, announcement | #65 | Open | |
| Launch | Release readiness check and version policy | #125 | Done | |
| Launch | Disclaimer: a calculation tool, decisions belong to the user | #171 | Done | |
| Launch | Documentation site meets WCAG AA contrast for the active navigation item | #144 | Done |
M4 · Traditional European methods¶
Gate: Golden cases green for every method.
| Epic | Task | Issue | Spec | Status |
|---|---|---|---|---|
| Asset-based method (simple and complex, with intangibles) | Implementation, golden cases, methodology page | #67 | 0004 | Open |
| Income-based method (normalised earnings, finite and infinite capitalisation) | Implementation, golden cases, methodology page | #69 | 0004 | Open |
| Mixed method with excess earnings / separate goodwill | Implementation, golden cases, methodology page | #71 | 0004 | Open |
| EVA and residual income | Implementation, golden cases, methodology page | #73 | Open | |
| Market multiples with user-provided comparables | Implementation, golden cases, methodology page | #75 | Open | |
| Cross-method valuation report (value range, stated assumptions) | Report generator from multiple results | #77 | Open |
M5 · Opt-in usage statistics¶
Gate: CI proves the payload carries no financial data; privacy notice reviewed by counsel.
| Epic | Task | Issue | Spec | Status |
|---|---|---|---|---|
| Telemetry RFC and implementation | Public RFC in Discussions (docs/telemetry.md) | #79 | Open | |
| Telemetry RFC and implementation | Client in adapters: consent, show/off, DO_NOT_TRACK | #80 | Open | |
| Telemetry RFC and implementation | Open-source collector without IP storage | #81 | Open | |
| Telemetry RFC and implementation | Public aggregated dashboard | #82 | Open |
M6 · v1.0 and real estate¶
Gate: Stable API with a published deprecation policy.
| Epic | Task | Issue | Spec | Status |
|---|---|---|---|---|
| Real estate module | Property DCF and direct capitalisation | #84 | Open | |
| Real estate module | Debt schedule, levered returns and equity waterfall | #85 | Open | |
| Real estate module | Market comparison approach with explicit adjustments | #86 | Open | |
| Platform | Scenarios and seeded Monte Carlo | #88 | Open | |
| Platform | WASM playground in the docs | #89 | Open | |
| Platform | Hosted MCP with API key and free tier | #90 | Open | |
| Platform | External methodological review | #91 | Open | |
| Platform | Jurisdiction profiles and translated manuals | #92 | Open | |
| Platform | Dated periods and a stub first period in the DCF | #167 | 0001 | Open |