portfolio-optimiser-commons/CHANGELOG.md

# 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.

## [Unreleased]

## [0.2.0] - 2026-09-23

### Removed

- **Two full-scale example bundles are removed from [`examples/`](examples/).** What remains is
  `bygg-energi-mikro` (the dev fixture with its golden suite) and the `nav-golden-hierarchy` /
  `nav-golden-escape` fixture pair. A consumer that vendors this repository loses the two
  directories on its next subtree pull; anything in a consumer that reads them by path must
  be removed or repointed first.

### Changed

- **[`skills/falsification-reviewer/references/example-evidence.json`](skills/falsification-reviewer/references/example-evidence.json)**
  now uses a building-energy scenario (daylight-responsive lighting control in an office
  building). The structure, the judgement (`undecided`), the evidence states and every rule the
  example demonstrates are unchanged; only the concept ids, titles and claim text changed.

### Added

- **[`scripts/check-excluded-topics.py`](scripts/check-excluded-topics.py)** — a repository
  hygiene gate: fails if any tracked path or text file matches a term list kept outside the tree,
  in `<git-common-dir>/info/excluded-topics`. It runs a self-test first (known positives must
  match, known negatives must not) and exits 2 rather than report a clean scan from a pattern that
  cannot find; without the term list it reports SKIPPED and exits 3.
- **[`method-spec.md`](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*. The supporting figure — 2 of 5 keys on a single
  source, reference corpus 2026-09-01 — is **the commissioning order's measurement, reported as
  theirs**, not one this repository made; the mechanism carries A1 without it. 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/`](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`](skills/falsification-reviewer/references/example-evidence.json)
  carries the frontmatter **verbatim and authoritative** (the line-oriented `frontmatter`
  projection beside it is informative and by construction cannot hold a block form), so the form
  question A1 settles is decidable from the example itself. The worked example returns
  `undecided`, not `survived`: the one concept that could have carried a refutation was
  unreadable, and a claim that was never attacked has not survived.

## [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
  two full-scale bundles, each with cost baseline, method note, sources, measures and a seed
  expert verdict (removed in [0.2.0]); 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.** The two full-scale bundles 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.2.0]: https://git.fromaitochitta.com/open/portfolio-optimiser-commons/releases/tag/v0.2.0
[0.1.0]: https://git.fromaitochitta.com/open/portfolio-optimiser-commons/releases/tag/v0.1.0