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
This commit is contained in:
Kjell Tore Guttormsen 2026-08-17 13:33:26 +02:00
commit fecdb97f1b

75
CHANGELOG.md Normal file
View file

@ -0,0 +1,75 @@
# 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