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
d6bced7d20
portfolio-optimiser ba om en SS11-rad for den portefoelje-brede budsjettsoemmen. Avvist paa akse: SS1 definerer metoden som «one project at a time», saa globalt tak + wave-admission er orkestrering OVER metoden. En MUST-rad ville gjort korrekt ett-prosjekt-implementasjon ikke-konform. Undersoekelsen fant et annet hull, og det er vaart: SS11 har 12 rader og ingen ankrer SS8 (fail-closed usage, strukturert stop-event, cap-nekt) eller SS10, mens SS1.3 sier «every load-bearing seam». Maalt, ikke antatt — det ene grep- treffet er substring-falsk-positiv («escaping»). Funn-notat, ikke underlag. Ingen rad skrevet, method-spec.md uroert, koeplassering operatoerens. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Qi5NoeXZmktJgmkD6bf89b |
||
|---|---|---|
| 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.