Changelog

This page lists every Board Ontology release. Each release has an immutable snapshot URL — pin to it if your integration needs reproducibility. See methodology § 4 for the versioning policy.

The entries below are appended by the docs build (see packages/docs/scripts/generate-ontology-changelog.ts) when a new ONTOLOGY_VERSION is detected. Hand-edit only above this marker:

v1.3.0 — 2026-05-20

metricBasis — structured, machine-filterable measurement metadata.

Where calculationPolicy (v1.1.0–v1.2.0) is free-text guidance for an LLM, metricBasis is a small set of enum axes a consumer can filter on deterministically — "all point-in-time metrics", "all cohort-based metrics", "all metrics measured on a cash basis".

New optional field metricBasis on every KPI, with five optional axes:

• timeBasis — point_in_time / period_flow / trailing_window
• moneyBasis — contracted_arr / recognized_revenue / cash / bookings
• cohortBasis — closed_start_cohort / all_active
• dateBasis — go_live / signed / period_close
• production — computed / primary (derived from other KPIs vs a raw input)

Each axis is independently optional and omitted when not meaningful — a KPI carries only the axes that apply. Populated for all 101 numeric KPIs; narrative (text) KPIs carry no metricBasis.

Additive — metricBasis is optional; consumers that ignore it see the same shape as v1.2.1. The JSON Schema at /api/ontology/schema.json picks up OntologyMetricBasis automatically (it is generated from the types).

Snapshot: /api/ontology/v/1.3.0/index.json

v1.2.1 — 2026-05-20

Correction — two KPI formulas were wrong. If you copied either formula, recompute.

An external review surfaced two formula strings (both predating the calculationPolicy work and never re-audited) that produced incorrect results:

• sales.cac_payback_period — the formula paired a per-customer numerator (CAC, the sales.cac KPI) with an aggregate denominator (Monthly New ARR). Per-customer ÷ aggregate yields months-per-customer, not months. Corrected: the numerator is now total fully-loaded S&M spend for the period, so both terms are period aggregates.
• finance.runway_months — the formula used max(operationally_available_cash, total_unrestricted_cash), which always selects the less conservative figure when working capital is a headwind — the exact pitfall the KPI's own description warns against. Corrected: the cash basis is now stated explicitly (operationally-available at Series A+, unrestricted at early stage); no max().

Both KPIs' calculationPolicy text was updated to match the corrected formulas. No schema change, no KPI added or removed — patch release.

Snapshot: /api/ontology/v/1.2.1/index.json

v1.2.0 — 2026-05-20

Calculation policy — 20 more KPIs, covering the rest of the ARR waterfall, the CAC family, and cash/runway.

v1.1.0 seeded calculationPolicy on the 5 highest-leverage KPIs. v1.2.0 extends coverage to 25 total — adding the metrics most likely to be miscomputed in agent-generated board packs after the original five.

Calculation policy added (20): finance.gross_burn_rate, finance.net_burn_rate, finance.operationally_available_cash, finance.runway_months, operations.rule_of_40, sales.avg_contract_value, sales.blended_cac_ratio, sales.cac, sales.churn_arr, sales.downgrades, sales.expansion, sales.expansion_cac_ratio, sales.gross_margin, sales.growth_rate_yoy, sales.new_business, sales.new_cac_ratio, sales.new_customers_added, sales.starting_arr — plus customers.logo_retention_rate and customers.logo_churn_rate.

Additive only — calculationPolicy remains optional; the 118 KPIs without one emit the same JSON shape as before. The remaining KPIs gain policy incrementally in future minor releases (see the draft pipeline at packages/shared-types/scripts/draft-calculation-policies.ts).

Snapshot: /api/ontology/v/1.2.0/index.json

v1.1.0 — 2026-05-19

Calculation policy — first 5 KPIs gain an agent-safe execution contract.

PR #1481 (v1.0.0) gave each KPI a definition, a formula, and interpretation guidance — enough for humans, not enough for AI agents asked to compute the metric from a company's messy data. v1.1.0 introduces calculationPolicy, a per-KPI block of inclusion / exclusion / required-input rules + edge cases + validation checks + common miscomputations. Free-text strings consumed by LLM agents at reasoning time (no DSL).

Calculation policy added (5): sales.arr, sales.carr, sales.cac_payback_period, customers.net_revenue_retention, customers.gross_revenue_retention.

Additive only — calculationPolicy is optional on every KPI; consumers with no use for it can ignore it entirely. The 138 KPIs without a policy emit the same JSON shape as in v1.0.0. Each editorial → published promotion (epic #1415) is a natural moment to add a policy block.

Snapshot: /api/ontology/v/1.1.0/index.json

v1.0.0 — 2026-05-19

Initial public release of the full Board Ontology.

• 143 KPIs across 7 domains: customers, finance, fundraising, hr, operations, product, sales.
• 27 anchored to third-party standards (tier: "published") — SMSB, KBCM/Sapphire, Mercer, Carta, SaaS Capital, Retently, NVCA, YC SAFE, SHRM.
• 116 I'mBoard-authored (tier: "editorial") — visible in the JSON / MCP surface, tier-labeled so consumers can filter to the strict subset.
• New: versioned response envelope { version, releasedAt, kpis } (breaking — the previous gated endpoint returned a flat array of 27).
• New: immutable snapshots at /api/ontology/v/1.0.0/ — pin consumers here for reproducibility.
• New: this changelog page.

Snapshot: /api/ontology/v/1.0.0/index.json