Framework-neutral shared core of the portfolio-optimiser method: the normative specs, example bundles and golden fixtures vendored by both reference implementations.
Kjell Tore Guttormsen
27cdce9eb2
Andre energi-eksempelbundle. Ni filer etter VEGLYS-malen: index i rota, type: project, 2 x type: hypothesis, methodology, reference, type: verdict, validator-input.json, cost-baseline.json. Ingen golden.json. Fire premisser fra forarbeidet ble MÅLT FEIL og er korrigert i bundelen: - CEDR REETS D2.1s 150 059 -> 33 114 kWh/år står under MODEL INPUTS og er et modellert ex-ante-anslag for en generisk referansetunnel, ikke en måling. - CEDR er ikke norsk. Forfattere AIT/TRL/Mouchel/DfL; Norge er medfinansiør av CEDR Call 2013, ikke datakilde. - NFF Publication 13s «vifta på full hastighet» gjelder byggefasen (stuffventilasjon under driving), ikke driftsventilasjon. - «€400k per inngang» er kostnaden for portalskjerming, ikke for belysning. Konsekvens: TUNNEL låner også sin realiseringsgrad. Det som faktisk skiller bundelen fra VEGLYS er at geometri og krav er norske, daterte og normative (Håndbok V124, april 2021, som beskriver tiltaket ved navn i § 9.6.1), at gap-mekanismen er en annen, og at M&V-asymmetrien er omvendt. Tiltaket er 3-trinns kontaktorstyring -> 13-trinns dimming av dagsonen. Modellert besparelse utledet av kvantiseringsoverskuddet i V124s egne to trinnrekker: 60 kW x (2/3 - 0,5425) x 4 500 t = 33 525 kWh/år. gap_source = control-tracking-overestimation, bevisst ULIK de to andre frøenes hours-of-use-overestimation: driftsfeil, ikke parameterfeil. realization_rate 0,72 lånt fra LBNL-5095E (dagslysstyring 39 % -> 28 % ved filtrering til faktiske installasjoner), merket som lån i provenance. Målt før commit: alle sju .md nåbare fra index med specens eget lenkemønster, type: i hver frontmatter, code/quantity/unit_cost identiske i de to JSON-ene, JSON-ene ASCII-rene, claimed/nominal_feasible = 1/3 eksakt, 0,72 x 33 525 = 24 138 lukker i heltall. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NGDYPSY5pg3TTEZpGhrf18 |
||
|---|---|---|
| docs/plan | ||
| examples | ||
| skills/expert-reviewer | ||
| .gitignore | ||
| CODE_OF_CONDUCT.md | ||
| CONCEPT.md | ||
| CONTRIBUTING.md | ||
| ingest-spec.md | ||
| LICENSE | ||
| method-spec.md | ||
| README.md | ||
| SECURITY.md | ||
portfolio-optimiser-commons
Framework-neutral shared core of the portfolio-optimiser method: the normative specs, example bundles and golden fixtures vendored by both reference implementations.
This repository is the source of truth for everything in the portfolio-optimiser method that is independent of any AI agent framework. It holds no runnable code — only normative specifications, example data, and expected outcomes.
Two reference implementations consume it, unchanged, as a git subtree at shared/:
portfolio-optimiser— the method on Microsoft Agent Framework (MAF);portfolio-optimiser-claude— the same method on the Claude Agent SDK.
Sharing one identical core is what makes the two implementations a fair comparison: both consume the same concept, the same example data, and the same expected outcomes, so the only thing that differs is the agent framework itself. The second implementation is built from the specifications alone, without reverse-engineering the reference code.
Contents
method-spec.md— the normative method specification, framework-neutral (the prose never names a concrete agent toolkit — enforced by a guard test): the 8-step loop, the verdict JSON contract, the inbox/outbox folder contract, the promotion-gate semantics, the IR projection + golden suite as the only ground truth, and the budget/provenance requirements.ingest-spec.md— the normative ingest specification, framework-neutral (same guard rule): the deterministic ingest step that materializes real data sources as OKF bundles BEFORE the loop — the polymorphic manifest schema (file/CSV, SQL, HTTP as extension point), the credential-reference rule, the verdict-layer reservation, the ingest provenance frontmatter with an explicit timestamp, the index-generation requirement, and the golden-extraction format.CONCEPT.md— the business concept, written for a non-specialist (e.g. a business developer at another company). Written in Norwegian.examples/bygg-energi-mikro/— the first example knowledge bundle (OKF / LLM-wiki): one office building, one LED-retrofit measure, with a seed expert verdict encoding the realization gap and a golden-suite of expected validator outcomes. A small dev fixture for exercising the agentic loop; a realistic full-scale example comes later.examples/nav-golden-hierarchy/andexamples/nav-golden-escape/— the nav-golden fixture class:bundle/in,expected-read-context.mdout, exercising the navigation contract (method-spec §3 Step 1) with one positive case (hierarchy, dedup, cycle termination, verdict exclusion) and one negative case (..and root-relative escapes, so a gate built on them can actually go red). Each case documents itself in its ownREADME.md. Informative listing only — no normative file refers to this class, and the comparison rule is deliberately not pinned (each case's README leaves a gate free to compare byte-exact or after trailing-whitespace normalization), so these are not ground truth in the sense method-spec §7 uses the word.skills/expert-reviewer/— the expert-reviewer persona as a framework-neutral Agent Skill: aSKILL.mdpersona prompt (energy-advisor / M&V role + the realization-gap methodology the validator cannot compute) and a canonicalreferences/example-verdict.json. Both reference implementations instantiate the reviewer from this one artifact; this repository stays pure data (each stack reads the JSON with its own loader).docs/plan/— the decision record: how each ruling in the specifications above was arrived at, including the ones that were later reversed. Working documents, not normative, and written in a mix of Norwegian and English.
Vendoring this repository
This repository is vendored, not installed — there is no package to add. Each consuming
repository carries it as a git subtree under shared/, so the specs and fixtures are present in
a normal checkout with no extra tooling.
Register the remote once, from the consuming repository's root:
git remote add commons https://git.fromaitochitta.com/open/portfolio-optimiser-commons.git
git subtree add --prefix=shared commons main --squash
Then pull updates with:
git subtree pull --prefix=shared commons main --squash
Sync is pull-only. All edits land here first — commit and push in this repository, then pull them into each consumer.
Never run git subtree push from a consuming repository. Observed 2026-07-03: because a
consumer's history contains commits that create and delete the shared/ prefix, the push re-split
leaked the consumer's entire history into this repository (cleaned up by force-push the same
day). Pull-only keeps this repository the clean source of truth.
Non-goals
- Not a runnable system. No pipeline, no CLI, no package. The specifications describe behaviour; the two implementation repositories provide it.
- No framework dependency. Nothing here may import or depend on a specific agent framework. If it does, it does not belong in this repository — that is what "framework-neutral" buys, and a guard test in each consumer enforces it for the two normative specs.
- Not a general-purpose knowledge-format standard. The bundle layout follows the upstream Open Knowledge Format where it applies; this repository does not seek to replace or extend it beyond what the method needs.
- Not a home for implementation decisions. Anything true of only one of the two stacks belongs in that stack's repository, not here.
- No inbound patches through this forge. See CONTRIBUTING.md.
License
MIT © 2026 Kjell Tore Guttormsen