open/portfolio-optimiser-commons
1
0
Fork 0
Code Issues Releases 1 Activity
Framework-neutral shared core of the portfolio-optimiser method: the normative specs, example bundles and golden fixtures vendored by both reference implementations.
58 commits 1 branch 2 tags 549 KiB
  • Python 100%
Find a file
Kjell Tore Guttormsen f35a22a304 fix(skills): eksempelet brøt skillens egen regel — undecided, ikke survived 
Tre defekter i ff7b9b7, funnet i review. Ingen av dem ville blitt fanget av
json.tool eller framework-guardene — alle tre er semantiske.

1. example-evidence.json sa `"judgement": "survived"` samtidig som ledger-noten sa at
   det ene konseptet som kunne båret en refutasjon var UNREADABLE. SKILL.md sier
   ordrett at `undecided` er «what you return when the evidence needed to refute the
   claim was not readable». Det ene arbeidseksempelet — det en nedstrøms agent leser
   som mønsteret, og det §11-testen materialiserer — demonstrerte altså nøyaktig
   inversjonen skillen finnes for å hindre: et hull i kunnskapsbasen konvertert til
   støtte for påstanden. Rettet til `undecided` + `judgement_note` som sier hvorfor.
   Eksempelet er bedre etterpå: det er nå den utførte demonstrasjonen av tilstanden
   skillen sier leseren mest trenger å kunne skille ut.

2. De to representasjonene i eksempelet var uenige med seg selv. Konsept 2s
   `frontmatter`-dict utelater `sources` (korrekt — en blokkliste er ikke uttrykkbar
   som én `key: value`-streng), mens `frontmatter_verbatim` har den. En §11-test som
   materialiserer fra dict-en ville utledet `state: absent`, ikke `unreadable`, og
   dermed mistet nøyaktig caset eksempelet finnes for. Grønn-men-død-formen §11 er
   til for å hindre. Nytt `materialisation_note`: `frontmatter_verbatim` er
   AUTORITATIV, `frontmatter` er dens linjeorienterte projeksjon og informativ.

3. method-spec.md skrev «Measured 2026-09-01 on the reference corpus: 2 of 5 keys …»
   i commons' EGEN stemme. Commons målte det ikke. Driftsregelen er eksplisitt —
   andres målinger føres som DERES — og teksten skal til en publisert flate. Tallet
   siteres nå ordrett fra ordren som bestilte A1, attribuert dit, med en setning om
   at mekanismen bærer A1 uten det: figuren er støtte, ikke grunn. Samme i CHANGELOG.
   Merk at konvensjonen er tvetydig i kildene: PM-dommen sier «produsenten skriver 2
   av 5 noekler», ordren sier «2 av 5 nøkler på ÉN kilde» — ulike påstander. Ordrens
   ordlyd er den siterte, og at det er et sitat er nå synlig.

Verifisering re-kjørt: konsumentens _FRAMEWORK_NAMES + _FORBIDDEN over 6 filer → 0
treff (kjent-positiv PASS); 'OKF bundle' 0 i skillen; json.tool OK; Steg 1-8 + MUST
intakt. Fortsatt IKKE PUSHET — origin/main..HEAD og open/main..HEAD begge 2 etter denne.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 17:11:39 +02:00
docs/plan docs(spec): Amendment A1 — sources som flow-sekvens + falsification-reviewer-persona 2026-09-02 17:02:53 +02:00
examples examples(tunnel): TUNNEL-HAUGLIA — strekkmål nummer to, på et korrigert premissgrunnlag 2026-08-09 15:13:54 +02:00
skills fix(skills): eksempelet brøt skillens egen regel — undecided, ikke survived 2026-09-02 17:11:39 +02:00
.gitignore chore(privacy): fjern de tre private identifikatorene fra publiserte filer 2026-08-24 16:47:55 +02:00
CHANGELOG.md fix(skills): eksempelet brøt skillens egen regel — undecided, ikke survived 2026-09-02 17:11:39 +02:00
CODE_OF_CONDUCT.md chore(release): publiseringsklar for open/ — README for standalone rot + MIT + policy-filer 2026-08-04 22:32:17 +02:00
CONCEPT.md docs(shared): konsept-notat til norsk (Forgejo-publikum = norsk marked) 2026-06-26 21:31:02 +02:00
CONTRIBUTING.md chore(release): publiseringsklar for open/ — README for standalone rot + MIT + policy-filer 2026-08-04 22:32:17 +02:00
ingest-spec.md docs(spec): §12 fører generated-undernøklene by og at som egne rader (O-A) 2026-08-25 06:30:32 +02:00
LICENSE chore(release): publiseringsklar for open/ — README for standalone rot + MIT + policy-filer 2026-08-04 22:32:17 +02:00
method-spec.md fix(skills): eksempelet brøt skillens egen regel — undecided, ikke survived 2026-09-02 17:11:39 +02:00
README.md docs(spec): «step 0 — explore» som informativ merknad; README lover ikke lenger et manglende eksempel 2026-08-24 17:58:31 +02:00
SECURITY.md fix(security): sikkerhetskontakt security@, ikke hello@ (D6-konsistens) 2026-08-21 11:23:16 +02:00

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

License: MIT

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/:

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; the two full-scale bundles below (veglys-fv-soer, tunnel-hauglia) are the realistic ones.
  • examples/veglys-fv-soer/ — an example knowledge bundle at realistic scale: a county-road street-lighting portfolio with two candidate measures (LED replacement of 2 500 of 9 500 HPS luminaires, and adaptive control), a seed expert verdict, the IR projection the deterministic validator reads, and the project's cost baseline. The realization gap is a parameter error — burn hours overestimated — on a Norwegian evidence base where many installations have no metering at all. Project layer fictional, literature layer real and cited. Written in Norwegian.
  • examples/tunnel-hauglia/ — an example knowledge bundle at realistic scale, same file layout as the veglys bundle: a two-tube road tunnel with two candidate measures (3-step to 13-step dimming of the entrance and transition zones, and passive portal screening). Its realization gap arises in operation rather than in the parameters, so the seed verdict carries gap_source: control-tracking-overestimation where both bygg-energi-mikro and veglys-fv-soer carry hours-of-use-overestimation — a second gap class, so a learning loop exercised here has seen more than one cause. Project layer fictional, literature layer real and cited. Written in Norwegian.
  • examples/nav-golden-hierarchy/ and examples/nav-golden-escape/ — the nav-golden fixture class: bundle/ in, expected-read-context.md out, 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 own README.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: a SKILL.md persona prompt (energy-advisor / M&V role + the realization-gap methodology the validator cannot compute) and a canonical references/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