Kjell Tore Guttormsen
ddaae5d637
Commons konsumeres som `shared/`-subtree av to repo som allerede ligger i `open/`. Innholdet var dermed offentlig fra før, men PEKEREN var det ikke: `shared/README.md` i open/portfolio-optimiser lenker til `ktg/`-namespacet og sier «All edits land in commons first (clone it, commit, push there)» — en URL en fremmed får 404 på. Dette gjør repoet publiserbart under open/. README: hodet var skrevet som om fila fortsatt lå i en konsuments `shared/`. H1 var `# shared/ — framework-neutral core`, og innledningen sa «this repository — the method built on MAF» — som beskriver et ANNET repo når fila leses fra commons' rot. Siste linje lenket til docs/plan/2026-06-26-maalbilde-agentic-loop.md, som ikke finnes her (den bor i portfolio-optimiser). Alle tre rettet; de to konsumentene er nå utgående lenker, ikke «dette repoet». Lagt til for `shared-asset`-klassen (repo-standard): LICENSE (MIT, byte-likt med soesknene) og `## Non-goals`. Klassen krever ikke `## Install` — repoet vendorers, det installeres ikke. CONTRIBUTING/SECURITY/CODE_OF_CONDUCT kreves av INGEN klasse; de er med for konsistens med de to soesknene. CONTRIBUTING er SKREVET OM, ikke kopiert: soesknenes versjon ber om Pull Requests, men org-ops slo PR-fanen av paa alle 19 repo fordi CONVENTIONS.md publiserer at PR-er ikke aksepteres. Aa kopiere den ville importert en motsigelse. SECURITY er omskrevet for et repo uten kjoerbar kode: angrepsflaten er spec- tekst som binder konsumentene, ikke et avhengighetstre. Gate: repo-standard v0.2.2, klasse shared-asset — 0 ERROR, 8 passerte. De 3 gjenstaaende WARN er falske positive mot nav-golden-fixturene (bundle-relative lenker + tilsiktede escape-nyttelaster som IKKE skal resolve). Fixturene er uroert: de konsumeres som ekte gate av portfolio-optimiser (0d50ab8). Verifisert foer commit: ingen secrets i sporet innhold eller i historikkens 37 commits; ingen e-post utover org-kontakten; STATE.md og *.local.md fortsatt usporet. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013XuKPjWwJZNUponVrhoyY1
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
|