open/portfolio-optimiser-commons
1
0
Fork 0
Code Issues Releases 1 Activity
portfolio-optimiser-commons/CHANGELOG.md
Kjell Tore Guttormsen fecdb97f1b docs(release): CHANGELOG + v0.1.0 — første taggede snitt av det publiserte kjernen 
Repoet har aldri hatt en tag. Dette er versjon én, og tallet er valgt ut fra
modenhet, ikke vane:

- method-spec §1 sin ufravikelige ærlighetsregel forbyr et artefakt å påstå mer
  enn implementasjonen gjør. En 1.0.0 under semver påstår at normativ tekst er
  frosset mot brytende endring. Den forpliktelsen er ikke gitt.
- SECURITY.md fører allerede «latest ✅ / < latest ❌» — intet støttevindu for
  eldre versjoner. En 1.0.0-tag ville motsagt tekst som alt står publisert.
- Normativ tekst endres fortsatt: V1 ratifisert 02.08, §7-ankerfiks 09.08, og
  SS11/§8 + SS12-undernøklene står ubesluttet i docs/plan/.
- Begge konsumenter puller `main` via git subtree --squash. Ingen pinner en ref,
  så tallet bærer i dag ingen operasjonell garanti.

At det er 0.1.0 og ikke 0.0.1: dette er et reelt, publisert, normativt konsumert
snitt — ikke en prototyp.

Ingen spec-tekst, README eller fixture er rørt. Kun CHANGELOG.md er lagt til, så
konsumentenes atomiske subtree-pull får en ny fil og ingen endret kontrakt.

Known-limitations-seksjonen fører to funn som ellers bare fantes i git-historikk
og lokal state: README lister tre av fem eksempelbundler, og 0.79/0.82 beskriver
samme case-klasse med to rater. Begge målt mot filene, ikke sitert fra state —
persona-eksempelet har ingen context_key, slik en kortform tidligere antydet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GgSJ4Tz7NQmbdnTdSYh7oE
2026-08-17 13:33:26 +02:00

4.7 KiB
Raw Permalink Blame History

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.

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.