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 ~3½ months from project start (end of Phase 3, week 14).

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.

LCI-first plan (Session 33)¶

Session 33 replaces the Session 31 sequence (catalog → geometry → comparator → wizard → earth). The tool stores, gates and applies Chiwara's life-cycle-inventory factors. It does not author impact factors (decision #31). Phase-1 scope is A1–A3, B4 and B6, GWP only (#32). The input contract is Option A: material quantities in, for any project (#33).

LCI store + provenance gate + admin management. Chiwara's LCI factors — proxy factors for materials without EPDs, earth above all — are stored behind the seed-EPD provenance gate, with ISO 14044 §4.2.3.6 data-quality metadata and the Weidema axes. The storage schema waits for Chiwara's LCI database structure.
A1–A3 fully wired. Resolve the declared-unit seam (per-m² vs per-kg) so every material resolves through the gate.
B4 replacement over the study period (decision #24).
B6 operational energy. Where the annual kWh comes from is deferred: computed by the tool from the thermal table, or supplied by Chiwara.
Comparison. The same engine runs on two material sets Chiwara provides, earth and conventional/BTC. No delta is shown unless both totals exist (decision #18).
Thin input + two-tier results UI (Option A). Material quantities are entered or imported. Results show as a sleek dashboard and a desktop detailed report. Specified in the Phase-1 UI spec (Session 34).
Fast-follow: Option-B catalog. A works → materials parametric catalog, built as versioned data (decision #28).
Deferred: Option-C geometry engine. Geometry → works, and the same-geometry auto-generation of the comparison.

A4 and A5 are a documented cut-off, not deleted. The code and parity tests stay. The modules are reported as EN 15978 "module not assessed", justified by their contribution %, and the cut-off applies to both variants alike.

Keur Songho ships as the validated built-in example. Its quantities come from the existing exact computation, which stays the parity reference (decision #23). The Session 31 design is kept as the spec for the deferred modules: Option B/C: catalog, estimator & comparator.

Deferred, not decided: the reference study period — 30 years (decision #15, which stands meanwhile) vs 50 years in the workbook. The B6 energy source (step 4) is decided (AR-80, 2026-10-01): Phase 1 takes supplied kWh/yr with its provenance (fork b). The tool computing it (fork a, EN ISO 52016-1 on vendored NASA POWER) is deferred to Phase 2.

Status snapshot — 2026-10-01

Declared-unit seam mechanism — done (#61). Basis-aware factors and the gate are in. It wires nothing; the per-m²/m³ records are still to be wired.
B6 fork-(b) plumbing — done (#62). Supplied kWh/yr, carrier and basis go to lca.b6. The carbon number is BLOCKED on EF_grid (AR-65).
AR-80 — resolved: fork (b) in Phase 1, fork (a) in Phase 2.
Next: B4 (step 3) and EF_grid sourcing (AR-65).

Waiting on Chiwara: the conventional/BTC material file (gates step 5) and the LCI database structure (gates step 1).

Decisions #31–#33 are new. #10 (frontend) and #29 (comparator) are amended and #28 (catalog) is resequenced, each with its original text kept. All are pending review in #53. #27 and #30 stand.

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`	Operational energy	Fork-(b) plumbing built (#62): supplied kWh/yr in, carbon BLOCKED on `EF_grid` (AR-65). Not parity-verified
`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 WIRED (cement-VDZ, rebar, crushed rock, sand — seeded and driving the reported factor as of Session 20, AR-63), 4 placeholder-but-unwired (per-m² declared units, AR-46; glass also AR-59), 5 BLOCKED, 1 earth-track, 1 cut-off, 3 unsourced. The immediate work is now to re-source the six A1-only records against EF-3.1 successor datasets and to settle the declared-unit seam that blocks the four vendored per-m² records (seam mechanism landed in #61; wiring those records is still to do).
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 over A1–A3, B4 and B6, 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. Session 33 exception: decision #32 moves b4 and b6 into Phase 1 (priority). Their scaffold files still say # TODO: Phase 2; the modules' own PRs update them.

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). Fork (a) of AR-80 — deferred to Phase 2; not on the Phase-1 B6 path.
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 (explicitly deferred, decision #33). Phase 1 since Session 33 (#32).
lca.b6 — Operational energy. Carries the "simplified — indicative" disclaimer per decision #17. Phase 1 since Session 33 (#32). Fork (b) — supplied kWh/yr — is the Phase-1 path (AR-80, resolved 2026-10-01); plumbing landed in #62, carbon BLOCKED on a sourced EF_grid (AR-65, AR-09). The climate-data service above is fork (a), Phase 2.
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. (Session 23: A1–A3, A4, A5 for Keur Songho; frontend/src/components/results/.)
Earth-vs-conventional comparison view — the Phase 1 deliverable the whole calculation set exists to produce. (Session 33: built in step 6 over the step-5 comparison of two provided material sets.)
Option-A input + two-tier results shell — material quantities entered or imported; a dashboard tier and a desktop detailed-report tier (step 6, amended decision #10). Spec: UI spec — Phase 1. (Session 36: the input wizard, Project → Materials → Review & compute → Results, is built in mock mode and lands on the per-stage view. Mock compute is canned; live compute waits on AR-72. The dashboard is next.)
~~Input wizard~~ (Session 33: deferred with Options B/C. The page proposal stays in design §6.4.)
Provenance / citation drill-down — every displayed number traceable to its source from the screen it appears on. (Session 23: per-row expanders on the results view — pedigree, citation, EPD id, per-leg A4 and per-item A5 sources. A CORRECTED row's reference value and Δ are not in the API yet, AR-71.)
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:

~~Seed the clean factors (rebar, crushed rock, sand, cement-VDZ) through the provenance gate.~~ Done — Session 20. Four factors now resolve from seed_epds/ through a runtime gate; cement reports 0.665, not the uncited 0.779. The A1–A3 total is still None — steps 2–4 below are what change that.
Re-source the six A1-only records against EF-3.1 successor datasets; flag or block what has no clean successor.
Obtain the earth data package (density + earth GWP) from the Chiwara track.
Rebuild the mass path (AR-46) from corrected volumes × sourced densities.
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.
#15 / #18 — Study period and comparative assertions. RSP defaults to 30 years and is set per project. A comparison needs the same GIA, RSP, climate and programme, plus an uncertainty band.
#27 — Two-path quantities model. An exact Keur Songho reference path (parity) and a geometry-estimator path (new projects), linked by an itemised calibration test.
#28 — Assembly catalog as versioned data. Recipes are provenance-carrying JSON records, and the catalog version is stamped on every result. Resequenced (Session 33) to the Option-B fast-follow.
#29 — Same-geometry comparator. One engine and two runs on one geometry. There is no delta without both totals and a band. Amended (Session 33): in Phase 1 the engine runs on two provided material sets; same-geometry auto-generation is deferred with Option C.
#30 — CMU conventional default. CMU walls, an RC strip foundation, an RC slab roof and cement plaster, with unsourced parameters BLOCKED. Applies as the catalog default once Option B exists.
#10 — Frontend. Amended (Session 33): a thin input + two-tier results shell is a Phase-1 deliverable.
#31 — LCI-first. The tool stores, gates and applies Chiwara's LCI factors; it does not author impact factors.
#32 — Phase-1 scope. A1–A3, B4, B6, GWP only; A4/A5 a documented, symmetric cut-off.
#33 — Input model. Option A (material quantities in) now; Option B (catalog) as a fast-follow; Option C (geometry) deferred.

The Session 33 additions and amendments are pending review in #53; each amended decision keeps its original text in PROJECT.md.

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.