portfolio-optimiser-commons/CHANGELOG.md

Changelog

All notable changes to this repository are documented here. The format follows Keep a Changelog, and versions follow Semantic Versioning.

Versioning posture. This repository is pre-1.0 by intent, not by omission. The normative text is still receiving amendments, and SECURITY.md supports latest only — no support window for earlier versions. Consumers vendor this repository with git subtree pull --prefix=shared commons main --squash and therefore track main, not a tag; a version number here labels a published cut, it does not pin anyone's checkout. A 1.0.0 will mean the normative specifications are frozen against breaking change — that commitment is not made yet.

Version numbers apply to the repository as a whole. The manifest_version in ingest-spec.md §4 is a separate, independent schema version and is not affected by this file.

[Unreleased]

Added

• method-spec.md §3 Step 1 — Amendment A1 (2026-09-02), multi-source provenance. sources is normatively written as a single-line flow sequence of one or more flow mappings; a block list MUST NOT be emitted, and a consumer that meets one reports it as unreadable, naming the shape and the number of entries seen. Line-oriented key: value parsing is untouched and restated as normative — A1 is a form pinned within it, not a relaxation of it. A single mapping normalises to a one-element tuple, so one source and several sources read the same way and last-write-wins never arises. Rationale, measured: line-oriented parsing carries one value per key, so a multi-source concept written as a block list loses every entry but one silently; on the reference corpus 2026-09-01, 2 of 5 keys were carried on a single source. Added the matching sources row to §12.
  • Axis note, in the spec: A1 binds emission. It does not reclassify a block list as malformed OKF, and the reference consumer's own decoder is quoted verbatim saying it is conformant-but-outside-the-accepted-subset.
  • Open finding, measured 2026-09-02, recorded not worked around: llm-ingestion-guard 1.2.0 rejects both forms ('[' indicator for the flow sequence, "a mapping is not expressible" for the block list), with title and verified: { by, at } as known-positives. A1 therefore pins a form no shipped version of that gate reads today.
• skills/falsification-reviewer/ — a second framework-neutral persona, alongside expert-reviewer: it attempts to refute a claim against a project's curated knowledge base, and reports what the knowledge base could not tell it as part of the verdict. Carries the evidence-state trichotomy (present / absent / unreadable, where unreadable names the shape it could not read and the count of entries seen), the adjudication set with unknown written explicitly rather than collapsed into proposed, the reliance threshold (a verdict may rest on a concept only when state is present and trust_tier is not unverified — everything else is reported as (state, reason, items_seen) and discounted, never rejected), and the rule that a refutation naming no refuter is not a refutation. references/example-evidence.json carries the frontmatter verbatim, so the form question A1 settles is decidable from the example itself.

0.1.0 - 2026-08-17

First tagged release. It carries the full contents accumulated since the repository was opened on 2026-06-26 and published at open/ on 2026-08-04; nothing in this release is new relative to main at 73136eb.

Added

• method-spec.md — the normative, framework-neutral method specification: the 8-step loop, the verdict JSON contract, the inbox/outbox folder contract, the promotion-gate semantics, the IR projection and golden suite as the only ground truth, and the budget/provenance requirements. RFC 2119 keywords; written to be implemented from the spec alone.
• ingest-spec.md — the normative, framework-neutral ingest specification: the deterministic pre-loop step that materializes real data sources as OKF bundles, with the polymorphic manifest schema (file/sql required, http an optional extension point), the credential-reference rule, the verdict-layer reservation, ingest provenance frontmatter with an explicit timestamp, the index-generation requirement, and the golden-extraction format.
• CONCEPT.md — the business concept for a non-specialist reader, in Norwegian.
• skills/expert-reviewer/ — the expert-reviewer persona as a framework-neutral Agent Skill: a SKILL.md persona prompt (energy-advisor / M&V role plus the realization-gap methodology the validator cannot compute) and a canonical references/example-verdict.json.
• Example knowledge bundles (OKF). Five directories under examples/: the bygg-energi-mikro dev fixture with its golden suite; the full-scale veglys-fv-soer and tunnel-hauglia bundles, each with cost baseline, method note, sources, measures and a seed expert verdict; and the nav-golden-hierarchy / nav-golden-escape fixture pair exercising the navigation contract of method-spec §3 Step 1 with one positive and one negative case. The nav-golden pair is an informative listing: no normative file refers to it, and its comparison rule is deliberately unpinned.
• docs/plan/ — the decision record behind each ruling in the specifications above, including the rulings later reversed. Working documents, not normative.
• Publication surface — README.md, LICENSE (MIT), CONTRIBUTING.md, SECURITY.md and CODE_OF_CONDUCT.md, landed 2026-08-04 when the repository was published at open/.

Known limitations at this release

Recorded because the honesty rule of method-spec §1 is unwaivable, and because a reader of the published surface would otherwise have to discover these by reading the git history:

• README.md lists three of the five example bundles. tunnel-hauglia and veglys-fv-soer are absent from the Contents section. No claim in the README is untrue, but the two largest bundles are invisible on the first screen.
• Two different realization rates describe the same case class. skills/expert-reviewer/references/example-verdict.json states realiseringsgrad=0.79 with an expected actual of 23700 NOK/yr; learning_surface in examples/bygg-energi-mikro/golden.json states realization_rate: 0.82 with modelled_saving_nok: 30000 and expected_actual_saving_nok: 24600. Both therefore imply the same modelled 30000 (23700 / 0.79 and 24600 / 0.82), and both describe a schedule-stipulated LED saving, yet the rates differ. This is not a specification contradiction: the persona example carries no context_key and never claims to be the bundle's verdict. Left unharmonized deliberately — 0.79 is traced through a consumer's byte-pinned golden transcript, so changing it here would turn a consumer's gate red.