Kjell Tore Guttormsen
22048eacd0
To operatørbeslutninger 24.08, ingen normativ tekst endret. method-spec.md §3: en informativ merknad mellom §3-ingressen og Step 1 om at mandatet kan UTLEDES før løkka starter. ALDRI et niende nummerert steg — et nummer i samme rekke arver rekkens autoritet, og aktiviteten er ikke normativ. Merknaden bruker derfor ingen RFC 2119-nøkkelord, får ingen `###`-overskrift, navngir ingen konkret agent-toolkit (framework-nøytralitets-vakta), legger ingen kontraktsfelt til og berører ingen søm i §11. Den sier eksplisitt at ingenting nedstrøms slakkes: Step 1s navigasjonsregler, Step 4s validator-gate og verdikt-lag-eksklusjonen står uendret uansett hvordan mandatet ble til. Ordrett «step 0» finnes nå to steder, på to akser som hver navngir sin egen: examples/nav-golden-escape/README.md:3 («catalog's requirement that step 0's gate…») og method-spec.md:66 («this specification defines no step zero»). README.md: bygg-energi-mikro-bulleten lovte fortsatt «a realistic full-scale example comes later». veglys-fv-soer og tunnel-hauglia er begge publisert og fyller rollen; setningen peker nå på dem i stedet for å love noe som mangler. Ordre 20260824T155506Z-3454831118-from-.claude, punkt 1 og 2.
118 lines
7.5 KiB
Markdown
118 lines
7.5 KiB
Markdown
# 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)
|
|
|
|
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; the two full-scale bundles below
|
|
([`veglys-fv-soer`](examples/veglys-fv-soer/), [`tunnel-hauglia`](examples/tunnel-hauglia/))
|
|
are the realistic ones.
|
|
- [`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
|