open/portfolio-optimiser-commons
1
0
Fork 0
Code Issues Releases 1 Activity
portfolio-optimiser-commons/CHANGELOG.md
Kjell Tore Guttormsen ff7b9b7c73 docs(spec): Amendment A1 — sources som flow-sekvens + falsification-reviewer-persona 
Ordre 20260902T113745Z-1250119413-from-.claude (S4), inkl. PM-amendmentet 02.09 14:20Z
som flyttet punkt 2 fra blokkliste til flow-sekvens.

1. skills/falsification-reviewer/ — andre framework-nøytrale persona ved siden av
   expert-reviewer, ordrett etter Handoff-specen (portfolio-optimiser plan.md § Handoff).
   Bærer evidens-trikotomien present/absent/unreadable der unreadable NAVNGIR formen den
   ikke kunne lese + items_seen; adjudication med `unknown` og `proposed` eksplisitt
   navngitt og aldri kollapset; K5-terskelen (B3) som skillens regel — en dom hviler på et
   konsept KUN når state == present OG trust_tier != unverified, alt annet rapporteres som
   (state, reason, items_seen) og DISKONTERES, aldri avvises (consumption-contract § 6.3:
   trust tiers er rådgivende signaler, ikke access control; machine-confirmed klarerer
   terskelen). En refutasjon som ikke navngir en refuter er ingen refutasjon.
   example-evidence.json bærer frontmatteren ORDRETT, ikke bare som dict — formspørsmålet
   A1 avgjør er ikke avgjørbart fra {"sources": [{...}]} alene.

2. method-spec.md § 3 Steg 1: Amendment A1. Linjeorientert parsing RESTATED som normativ
   (ikke relaksert); `sources` pinnes som énlinjes flow-sekvens av én eller flere
   flow-mappinger, blokkliste MÅ IKKE emitteres, og en konsument som møter en rapporterer
   den som unreadable med form + antall. Ny rad i § 12. Begrunnelse målt: linjeorientert
   parsing har én verdi per nøkkel, så en blokkliste mister alle oppføringer unntatt én
   STILLE; K5-taket målt 01.09 = 2 av 5 nøkler på ÉN kilde.

   AKSE-NOTE, skrevet inn i spec-en: A1 binder EMISJON. Konsumentens egen plan sier
   ordrett «A block sequence and a block mapping are both conformant OKF; they are simply
   outside the accepted subset, and the decoder is not entitled to an opinion about whether
   the author erred» — sitert verbatim i spec-en. Et flatt forbud uten denne noten ville
   gjort konsumentens egen SPEC-kanoniske fikstur ikke-konform.

   ÅPENT FUNN, målt 02.09 mot llm-ingestion-guard 1.2.0 (kjent-positiv: title PASS,
   verified flow-mapping PASS): porten AVVISER BEGGE former — flow-sekvens med
   «disallowed YAML indicator '['», blokkliste med «a mapping is not expressible». A1
   pinner altså en form ingen shippet versjon av porten leser i dag. Ført i spec-en og
   CHANGELOG, ikke omgått: alternativet feiler av en verre grunn (mister data).

3. De to køplasserte postene fra 25.08 STÅR (§ 10.1 og § 11.1). Ordren spurte på
   SCOPE-aksen; avslaget ligger på RATIFIKASJONS-aksen — begge er ren spec-tekst, men
   løsningen er fortsatt operatørens å velge blant åpne opsjoner (D-A/D-F), og
   :29-referenten endrer en konformans-MUST to konsumenter måles mot. Premisser re-målt:
   git log --since=2026-08-25 tomt, ingen ordre i arkivet mellom 25.08 og 02.09,
   ingest-spec.md:29 ordrett uendret.

Verifisering kjørt (commons eier ingen kjørbar kode — nevner: 69 filer, 0 .py/.sh/CI):
konsumentens egne guards kjørt mot artefaktene her — _FRAMEWORK_NAMES (14 navn,
IGNORECASE) og persona-testens _FORBIDDEN over 6 filer: 0 treff, kjent-positiv PASS.
grep -c 'OKF bundle' i skillen: 0 (kjent-positiv 'knowledge bundle': 1). json.tool OK.
Steg 1-8-markørene og MUST-språket intakt etter amendmentet.

IKKE PUSHET (open/ krever operatørtoken). Ingen versjonsbump, ingen tag.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 17:02:53 +02:00

110 lines
7.3 KiB
Markdown
Raw Blame History

# 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]
### Added
- **[`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*; 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/`](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, 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`](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
Reference in a new issue View git blame Copy permalink