102 lines
6.1 KiB
Markdown
102 lines
6.1 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; a realistic full-scale example comes later.
|
|
- [`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
|