Skip to content

Development Roadmap

Standards: ISO 14040 / 14044 → EN 15804+A2 → EN 15978. ISO 21931. EF 3.1 characterisation. Licence: AGPL-3.0-or-later. Status: pre-alpha, targeting v1.0 in ~4 months from project start.

This page describes where the project is going and why. It complements — and does not duplicate — the Action register (open items), the Module map (per-module build state), and the Changelog (what has already shipped). Sequencing here is phase-relative and dependency-driven, not calendar-dated: milestones unlock when their inputs exist, and several inputs are field data outside the software team's control.

How to read this roadmap

Two principles shape everything below.

A module being built is not the same as it producing a number. Every calculation module follows E = weight × factor. A module can be fully implemented, tested, and merged while still emitting None, because one or both halves of that product are deliberately BLOCKED until a defensible value exists. Green in CI means the code is correct; it does not mean a result is reportable. The roadmap therefore tracks two things separately: modules built, and factors and masses sourced.

No number enters the tool without a traceable, permitted source. This is the project's core commitment and its main differentiator. Where a defensible value does not yet exist, the tool raises rather than guesses. Much of the roadmap is consequently about sourcing and attribution, not about writing more code.

Phase 1 — Calculation engine and first citable results (current)

Objective: compute the earth-vs-conventional comparison end-to-end for the first reference building (Keur Songho), with every reported number traceable to a permitted source.

Modules

Each stage module is reverse-engineered from the reference workbook, verified against it by a parity test (decision #23), and merged behind the provenance discipline. Current state:

Module Stage State
quantities Bill of quantities (Keur Songho) Built, parity-tested
lca.a1_a3 Product stage Built, parity-tested — emits None/BLOCKED until factors land
lca.a4 Transport to site Built, parity-tested — BLOCKED pending transport factors
lca.a5 Construction / installation Built, parity-tested — site-energy factor BLOCKED (decision #26)
lca.b6, lca.c1, lca.c2, lca.c3, lca.c4, lca.b4, lca.d Use / end-of-life / beyond Scaffold only — licence header + TODO, no logic yet

Reconciliation note (resolved, Session 14): the scaffold files tag themselves Phase 2, while the module map listed some of the same stages as v1 / not-started. Reconciled against the source files: all seven scaffolds are Phase 2, matching the TODO they carry, and "in scope for v1" was never in conflict with that — v1.0 ships at the end of Phase 3. The phase column on the module map is no longer provisional.

The two gating halves

A first citable result for Keur Songho requires both halves of E = weight × factor to exist for at least the dominant materials:

  • Factor half — seed EPDs. Tracked on the Seed-EPD scoreboard. Of the 18-material inventory: 4 LEGIT, 4 placeholder (flagged), 5 BLOCKED, 1 earth-track, 1 cut-off, 3 unsourced. The immediate work is to seed the clean records (rebar, crushed rock, sand, cement-VDZ) through the provenance gate, then re-source the six A1-only records against EF-3.1 successor datasets.
  • Mass half — the mass-path rebuild (AR-46) and earth densities (AR-47). The quantities path must be rebuilt from corrected volumes × sourced densities before any A1–A3 total can be non-None. Earth density is field data owed by the Chiwara track; it cannot be substituted from a European database (decision #26).

Phase 1 is complete when Keur Songho produces a defensible earth-vs-conventional GWP comparison, every input either sourced or explicitly flagged, and no module leaks an uncited number.

Phase 1 progress (4 / 12 modules)

Twelve modules make up the v1 calculation set. Four are built, parity-tested and merged; eight are not started. Four of the eight — b4, c3, c4, d — have a committed reverse-engineering spec; the rest do not.

Built in Phase 1, scheduled in Phase 2

This checklist tracks the v1 module set in one place, which is why it lists modules the phase plan schedules for Phase 2. Every unbuilt stage module (b4, b6, c1–c4, d) and the climate/thermal work is Phase 2, matching the # TODO: Phase 2 the scaffold files themselves declare and the module map status table. Ticking a box here does not move a module into Phase 1; it records that the v1 set is 4/12 complete.

Research — Excel reverse-engineering and methodology

  • Material impact database spec — A1–A3 source formulas extracted from 2_lca_vn.xlsx (spec)
  • A4 transport spec (spec)
  • A5 construction spec (spec)
  • B4 / C3 / C4 / D spec — formulas extracted, verdicts assigned, modules not yet built (spec)
  • B6 / C1 / C2 specs — no Step-1 reverse-engineering yet. C1 and C2 must not be built against the uncited literals they inherit from A5 and A4 (AR-57, AR-17)
  • Climate data licence clearance — Session 17 (clearance); resolved AR-31, opened AR-60 … AR-63

Backend — calculation modules (API + OpenAPI docs)

  • quantities — Bill-of-quantities intake and material explosion, Keur Songho reference project. Kalan Deme So raises NotImplementedError until Phase 2
  • lca.a1_a3 — Product-stage embodied impact, E = weight × factor per material. Emits None while any factor is BLOCKED
  • lca.a4 — Transport to site, per tonne-kilometre. Emits None — both transport factors are BLOCKED (AR-01, AR-02)
  • lca.a5 — Construction-stage on-site plant energy. Reports 1 080 kWh of energy demand; GWP total is None, BLOCKED pending AR-54 (site-energy factor). Scope is plant energy only, declared under EN 15804+A2 §6.3.5 (AR-58)
  • Climate-data service (NASA POWER, vendored) + EN ISO 52016-1 hourly kernel — replaces the originally planned ASHRAE-table interpolation service (AR-31 resolved, AR-60). A from-scratch build: no cooling-load code exists to migrate. Latitude selection must diverge from the workbook, not match it (AR-62)
  • lca.b4 — Replacement over the study period, ⌈RSP ÷ RSL⌉ − 1. Spec committed; gated on sourced RSL values (decision #24) and the 30-vs-50-year study-period conflict
  • lca.b6 — Operational energy. Depends on the climate-data service above and on a verified grid factor (AR-09); carries the "simplified — indicative" disclaimer per decision #17
  • lca.c1 / c2 / c3 / c4 — end-of-life stages (4 modules). C3, C4 have specs; C1 and C2 do not, and each inherits a BLOCKED factor from an earlier stage (AR-57, AR-17)
  • lca.d — Benefits and loads beyond the system boundary. Spec committed. Always reported as a separate line item, never netted into the A–C total (EN 15804+A2 §6.4.3.2)

Frontend — UI/UX

In scope for this phase; not yet started. Frontend work starts alongside the backend API rather than waiting for the calculation set to close, and is expected to iterate as Phase 2 adds modules and the second reference building. Root ROADMAP.md schedules the three headline frontend deliverables under its Phase 3; this page starts the track in Phase 1 and expects it to run across both.

  • Project / building intake UI — Keur Songho now; Kalan Deme So once the quantities module's NotImplementedError is resolved in Phase 2
  • Per-stage results view — must render BLOCKED / None states honestly, each with its reason. Never hidden, never zero-filled: a missing factor is a visible result, not a gap in the chart
  • Earth-vs-conventional comparison view — the Phase 1 deliverable the whole calculation set exists to produce
  • Provenance / citation drill-down — every displayed number traceable to its source from the screen it appears on
  • Frontend test suite (component + integration), held to the same non-optional standard as the backend suite per AGENTS.md

Integration — frontend ↔ API

In scope for this phase; not yet started. Wiring the UI to the API tracks the Frontend work above.

  • Typed API client generated from the OpenAPI schema — generated, not hand-written, so the client cannot drift from the contract
  • Frontend ↔ API integration test against a running or mocked backend
  • CI wiring for the frontend build and test run — no frontend job exists in ci.yml yet

Out of scope for Phase 1: operational-energy settings UI and ASHRAE-based methods (superseded — see AR-31 and the climate data licence clearance).

Phase 2 — Completeness

Objective: widen from a single building and a partial stage set to a full, second-building- validated assessment.

  • Second reference building (Kalan Deme So). The quantities module currently raises NotImplementedError for it; Phase 2 builds its bill-of-quantities path using the same fork-per-typology pattern.
  • Remaining life-cycle stages. Reverse-engineer and build the scaffold modules (B4 replacement, C1–C4 end-of-life, D beyond-system-boundary) with the same parity + BLOCKED discipline. Each inherits any uncited workbook literal as a BLOCKED factor from the start — e.g. C1 must block the 0.26 site-energy value it inherits from A5 (AR-57).
  • Full earth data package. The Chiwara/CRATerre primary-data set: as-placed bulk density and A1–A3 earth GWP (AR-47, AR-03). This is the project's novel contribution and gates the earth half of every stage.
  • Thermal and operational energy. The thermal and energy services, feeding B6. Operational energy blocks on the EU grid factor and awaits a verified Senegalese grid factor (decision #26, AR-09).
  • Supporting services. proxy_engine, pedigree/DQI, interpolation, uncertainty, and reporting move from stub to functional.

Phase 3 — Release (v1.0 ships at the end of this phase)

Objective: turn a working calculation engine into a released, publicly auditable tool.

  • Public repository flip. The repository is private through Phases 1–2; it opens once the methodology is stable and licence clearance is complete.
  • Licensing and attribution closure. AGPL-3.0 compliance, the contributor licence agreement, and per-source attribution (e.g. the DL-DE-BY-2.0 string on every ÖKOBAUDAT record) verified across the codebase and data set. See EPD source licence clearance.
  • v1.0.0 release tag. v1.0 means a complete, released tool. The tag is not held for the external critical review; that review is Phase 4 and examines the released tool.

Phase 4 — External validation and dissemination (post-v1.0)

Objective: make an already-released methodology publicly defensible, and make it known.

Everything in this phase follows the v1.0.0 tag. None of it gates the release.

  • External ISO 14071 critical review. The methodology specification is written as the target of an ISO 14071 critical review — an independent check of the LCA's methodological soundness.
  • Methodology white paper. Drafted and submitted (Building & Environment / Journal of Cleaner Production / IJLCA), with submission timing coordinated against the critical review.
  • Institutional partnerships. IFC EDGE, UNEP GlobalABC and DGNB approached for a formal recognition path — discussions, not commitments.

Critical path to the first citable number

The single most important sequence — everything else is secondary to this:

  1. Seed the clean factors (rebar, crushed rock, sand, cement-VDZ) through the provenance gate.
  2. Re-source the six A1-only records against EF-3.1 successor datasets; flag or block what has no clean successor.
  3. Obtain the earth data package (density + earth GWP) from the Chiwara track.
  4. Rebuild the mass path (AR-46) from corrected volumes × sourced densities.
  5. A first Keur Songho earth-vs-conventional GWP result becomes computable and citable.

Steps 1–2 are software-and-sourcing work in progress. Steps 3–4 gate on field data and are the true long poles; no amount of additional module-building shortens them.

Dependencies outside the software team

  • Chiwara field data. Earth density and GWP, the "OMPU" source document, several suspect workbook numbers, brick composition, slab reinforcement, the anti-termite treatment area, the construction-site power source, material service lives, and transport distances. These are enumerated in the Chiwara attribution requests and the corresponding action-register rows.
  • External data availability. EF-3.1 successor datasets on ÖKOBAUDAT for the A1-only materials; a verified Senegalese grid factor for operational and site energy.
  • Legal. Licence clearance for every data source; only ÖKOBAUDAT is vendorable (decision #25).

Decision anchors

The roadmap is shaped by decisions locked in the project record; the load-bearing ones:

  • #23 — Parity verdict framework. VALIDATED (parity ≤0.1 %), CORRECTED (divergence test), BLOCKED (raise), EXPERT-JUDGEMENT (named attribution, never for impact factors).
  • #25 — Vendoring rights. ÖKOBAUDAT (DL-DE-BY-2.0) is the sole vendorable source; others are cite/runtime-only or blocked.
  • #26 — Geographic data policy. Earth = local/primary only; globally-similar materials = ÖKOBAUDAT interim with a "pending African data" flag; energy stages block on the EU grid.
  • Seed-EPD provenance gate. Every seed record carries a source citation, five Weidema data- quality axes, a written justification, and an integrity test that resolves the citation.

Out of scope for v1

Use-stage sub-modules B1, B2, B3, B5, and B7 are excluded from v1 by decision. A5 is scoped to on-site plant energy only for v1; the other EN 15804+A2 A5 sub-scopes (material wastage and its upstream burden, packaging waste, site water, consumables) are a documented scope limitation pending data, not a defect.