ADR 0005 — Phase 5 Re-Cut: Full Engine First, Reproduction as Milestone, Offer as Deadline¶
Status¶
Accepted (2026-09-23)
Context¶
Phase 4 delivered the modeling blueprint (BU catalog, transaction map, DS coupling, BU object interface, unitary core). Two competing priorities emerged:
- Owner wants the full modeling capability at a functional level — all BUs, switchable via profiles — because architecture and math foundations are the current focus.
- Owner warns against endless foundation building: "we need to produce things soon" — results for commercial, finance, marketing, operations/software teams, with rider buy-in as the priority.
Earlier assessment proposed a rider-first slice (build RIDER alone, offer early). Owner overrode: complete engine capability first, but reproduce earlier models as the milestone, and produce offer artifacts soon.
Decision¶
Phase 5 is re-cut into four milestones, each ending with a reproduction check against an earlier model — every step is verifiable against numbers that already exist, so the work cannot drift:
| Step | Build | Reproduction target (done = matches) |
|---|---|---|
| 5.1 | BU object base (set_parameters / apply_inputs / advance / query, persistent state) + RIDER wrapper | existing vor_model.py outputs through the new interface; legacy test suite passes |
| 5.2 | BCS, SNS, EPS wrappers + DS coupling (demand/supply ratio, shared utilization) | existing bcs/sns/eps_model.py suites pass through the new interface; FFD/EED glue preserved |
| 5.3 | v12 cross-check + sensitivity harness | separated roster, consolidated (H2 eliminated), matches v12 Line 1 on identical inputs; single IRR convention |
| 5.4 | Output matrix + first offer artifact | "Mombasa tricycle battery swap offer" page + rider sheet (HTML + CSV) |
Rules that keep this out of foundation-swamp:
- No new math without a reproduction target. Refactors wrap existing, tested calculation modules (
models/*_model.py); they do not rewrite them. - 5.4 is not optional. Even if 5.3 slips, an offer artifact ships using whatever BU coverage exists.
- Profiles carry market specifics (USD basis, ISO units); missing owner inputs (tricycle price, daily km, willingness-to-pay) enter as provenance-tagged
pending-inputvalues with range stress tests.
Consequences¶
- Engine capability (owner's architecture focus) and offer output (owner's business pressure) are both scheduled; neither blocks the other beyond 5.2.
- The legacy models remain the source of numerical truth until 5.3 replaces them with the v12 oracle.
- CNS, VSP remain registered-only until a profile needs them.