portfolio-optimiser-commons/README.md

# 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.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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`](https://git.fromaitochitta.com/open/portfolio-optimiser) — the
  method on **Microsoft Agent Framework (MAF)**;
- [`portfolio-optimiser-claude`](https://git.fromaitochitta.com/open/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`](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`](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`](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/`](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/veglys-fv-soer/`](examples/veglys-fv-soer/) — an example knowledge bundle at realistic
  scale: a county-road street-lighting portfolio with two candidate measures (LED replacement of
  2 500 of 9 500 HPS luminaires, and adaptive control), a seed expert verdict, the IR projection
  the deterministic validator reads, and the project's cost baseline. The realization gap is a
  parameter error — burn hours overestimated — on a Norwegian evidence base where many
  installations have no metering at all. Project layer fictional, literature layer real and cited.
  Written in Norwegian.
- [`examples/tunnel-hauglia/`](examples/tunnel-hauglia/) — an example knowledge bundle at realistic
  scale, same file layout as the veglys bundle: a two-tube road tunnel with two candidate measures
  (3-step to 13-step dimming of the entrance and transition zones, and passive portal screening).
  Its realization gap arises in operation rather than in the parameters, so the seed verdict carries
  `gap_source: control-tracking-overestimation` where both bygg-energi-mikro and veglys-fv-soer
  carry `hours-of-use-overestimation` — a second gap class, so a learning loop exercised here has seen
  more than one cause. Project layer fictional, literature layer real and cited. Written in Norwegian.
- [`examples/nav-golden-hierarchy/`](examples/nav-golden-hierarchy/) and
  [`examples/nav-golden-escape/`](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/`](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/`](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:

```sh
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:

```sh
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](CONTRIBUTING.md).

## License

[MIT](LICENSE) © 2026 Kjell Tore Guttormsen