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
d63e45d1f1
STATE bar siden 07-27 et ugatet NESTE STEG: sjekk om Google OKF har nådd v0.2, fordi catalogs 0.1→0.2-bump da kunne ha kollapset som avklaring. Sjekken er gjort. Google er på v0.2 (blog, 2026-07-25) — men hypotesen holder ikke, og tre premisser avvek fra ground truth: 1. Svaret lå allerede i eget arkiv. llm-ingestion-okf skrev det ordrett 2026-07-26 («OKF v0.2 er ute»), og hele V1-sporet er bygget på v0.2. Observasjonen ble ført som «uverifisert» i fire økter mens den samtidig var bærende premiss i nabosporet. STATE-defekt, ikke funn. 2. catalog er på 0.3 (1ca27f6, 07-31), ikke 0.2. 3. Bumpens primærgrunn var §3-gulvet (6a72b26: «enforce §3 okf_version shape»), ikke forvekslbarhet — den var ført som bevisst sidegevinst i spec.md:12-14. STATE byttet om primær og sekundær og bygget et neste steg på omvendingen. Avklaringen kan uansett ikke kollapse: catalogs konvensjonsversjon og okf_version-verdien er to ortogonale akser (spec.md:13-14, :70-72, :245-246). Akse-forveksling nr. 13 — denne gangen vår egen. Det ene som står igjen (spec.md sier «currently 0.1» mens :67 siterer upstreams 0.2-eksempel) er ikke en defekt: §12 :246-247 hjemler re-sjekken, og den er catalogs å utløse. Vi er ikke respondent. Ingen melding sendt. Catalog-ankre lest read-only @ 1ca27f6; ingenting skrevet i det repoet. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N1LAtsgpGik3RGJCKv7fAV |
||
|---|---|---|
| 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.