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
ab0ea8f722
Fire innkomne meldinger, hvert premiss målt mot kilden før noe ble skrevet.
V1 (§3.1, ny): po-claudes «generated er et eierskaps-predikat i v0.3.2» er
målt. Porten er en KONJUNKSJON (generated=="true" AND ingest_manifest) — deres
egen kodekommentar sier det, og det er ordrett hva §3 krever («the check is on
the complete stamp, never on the individual field names»). Ingen predikat-
konflikt; V1-blokkeringen er dermed oppløst ved måling. Det meldingen FAKTISK
avdekker er en migrasjonskostnad: emitter (:103) og port (:89) kobles av
strengliteralen "true", så en mapping-form feller begge samtidig — under O1 og
O2 likt. Og en versjonsforskjell ingen av meldingene så: porten er GLOBAL i
v0.3.2 (som begge konsumenter kjører) men PER MANIFEST i okfs HEAD.
V1 (§6.2.1, ny): okfs fire svar, ført som DERES måling og ikke foldet inn i
våre tall. Q1 gjør :29 til en misforståelse i spec-teksten, ikke en drift som
skal lukkes — settet var aldri ment som den delte fasiten. Q2 gir fire utalte
sømmer (NULL ⊥ tom celle, kredensial-indireksjon, N>1-indeks, http-hermetikk).
Q3 bekreftet i begge trær: stampen bærer FILNAVNET, ikke bare bytene.
V1 (§7, ny): aktørkonvensjonen for intervju-født innhold er rutet hit på en
navnekollisjon — de tre aktørformene er OKF SPEC.md §7, vår §7 sier «Literally
true» og har 0 treff på aktørformer. Lag-skillet gjør spørsmålet uavhengig av
alle fire opsjoner: operatøren trenger IKKE løse det for å løse V1.
amendment-underlag §7.2: siteringen «:112-114» var HEAD-relativ OG av med én
linje. Ref-bundet til seksjon + ordrett tekst med begge refs oppgitt. Målt:
begge konsumenter står på
|
||
|---|---|---|
| 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.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.