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.

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

• portfolio-optimiser — the method on Microsoft Agent Framework (MAF);
• portfolio-optimiser-claude — the same method on the Claude Agent 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. 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; a realistic full-scale example comes later.
• 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