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
ef31ddabac
llm-ingestion-okf svarte på pin-forespørselen. Tre ting falt på plass, og ett premiss i §4.1 viste seg for svakt. Grunnlaget står ordrett uendret; §4.2 er status, ikke omskriving. PINNEN: 2504011 (v0.2-fiksturen, pushet til open/llm-ingestion-okf). Sagt eksplisitt som pin — skillet mot de siterte refene 6f42c10/ed08ac1 holdt. Deres v0.2-fikstur bar O2-formen allerede fra c90171d; ført som DERES måling. <fast id> = process:okf-ingest (operatøren). Okfs eget forslag. De foreslo først process:llm-ingestion-okf og argumenterte samtidig mot den. Riktig, og strengere enn de kunne se: :8-9 gjør prosaen framework-nøytral ved regel, og :7-8 krever at specen kan implementeres «from this spec alone». Å normere produsentens repo-navn ville tvunget enhver annen konform implementasjon til å skrive det navnet i sin egen output. - Forbehold ført eksplisitt: §11-seamen :282 («names a concrete agent toolkit») treffer IKKE ordrett, siden okf er en ingest-impl. og ikke en agent-toolkit. Utelukkelsen hviler på :7-8. Raden er ikke ført sterkere enn den bærer. SITERINGEN ER IKKE NORMATIV — formen er usitert. Fjerde gang et spørsmål som så åpent ut var avgjort av frossen tekst (etter D-B, :29-vs-O1 og :158): method-spec.md:90 parser frontmatter «line-oriented as key: value STRINGS», frossen siden |
||
|---|---|---|
| docs/plan | ||
| examples | ||
| skills/expert-reviewer | ||
| .gitignore | ||
| CONCEPT.md | ||
| ingest-spec.md | ||
| method-spec.md | ||
| README.md | ||
shared/ — framework-neutral core
This directory holds the parts of the project that are independent of any AI agent framework and are meant to be shared, unchanged, between both reference implementations:
- this repository — the method built on Microsoft Agent Framework (MAF);
- a sibling repository (built later, in sequence) — the same method on the Claude Agents 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.
Contents (growing)
CONCEPT.md— the business concept, written for a non-specialist (e.g. a business developer at another company).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;shared/stays pure data (each stack reads the JSON with its own loader).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. The sibling implementation is built from this spec alone, without reverse-engineering the reference code.ingest-spec.md— the normative ingest specification, framework-neutral (same guard rule as the method spec): 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.
Rules
- Nothing in here may import or depend on a specific agent framework. If it does,
it does not belong in
shared/. - Repo layout (decision R1, realized 2026-07-03): the shared core lives in its own
repository,
portfolio-optimiser-commons— the source of truth. Each implementation repo consumes it as a git subtree at this unchangedshared/path (so tests and thePORTFOLIO_SHARED_ROOTdefault resolver are unaffected). Do not edit commons content anywhere else without syncing.
Subtree sync (pull-only — run from the consuming repo's root)
The remote is registered as commons
(ssh://git@git.fromaitochitta.com/ktg/portfolio-optimiser-commons.git).
All edits land in commons first (clone it, commit, push there), then each consuming repo pulls them in:
git subtree pull --prefix=shared commons main --squash
Never run git subtree push from a consuming repo. Observed 2026-07-03: because
this repo's history contains commits that create/delete the shared/ prefix, the
push re-split leaked the consumer's entire history into commons (cleaned up by
force-push the same day). Pull-only keeps commons the clean source of truth.
See the target picture for the full architecture: docs/plan/2026-06-26-maalbilde-agentic-loop.md.