# Changelog

All notable changes to this repository are documented here. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

**Versioning posture.** This repository is pre-1.0 by intent, not by omission. The normative
text is still receiving amendments, and [SECURITY.md](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`](ingest-spec.md) §4 is a separate, independent schema version and is not
affected by this file.

## [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`](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`](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`](CONCEPT.md)** — the business concept for a non-specialist reader, in
  Norwegian.
- **[`skills/expert-reviewer/`](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/`](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/`](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.

[0.1.0]: https://git.fromaitochitta.com/open/portfolio-optimiser-commons/releases/tag/v0.1.0