open/portfolio-optimiser-commons
1
0
Fork 0
Code Issues Releases Activity
Framework-neutral shared core of the portfolio-optimiser method: the normative specs, example bundles and golden fixtures vendored by both reference implementations.
21 commits 1 branch 0 tags 282 KiB
Find a file
Kjell Tore Guttormsen 29ad8ca4f4 docs(plan): amendment-underlag — frossen tekst per køpunkt, med målt fasit-effekt 
Leverer det generelle underlaget portfolio-optimiser klarerte som trygt arbeid
(2026-07-25 05:09Z pkt. 3): per køpunkt hvilke spec-seksjoner det rører og hva
frossen tekst sier i dag (fil + linje, verbatim). Ingen foreslått ny tekst —
pakken eies oppstrøms og ratifiseres av operatøren.

Tre funn utover ren kartlegging, alle verifisert mot HEAD før de ble skrevet:

- D-A#3 (ledende "/") trenger ingen amendment: method-spec.md:67-71 sier det
  allerede (landet 9801d35), og §11-raden :425 har rød-betingelsen. Det er et
  konformitetsgap i implementasjonen, ikke et spec-hull.
- Oppstrøms-anker shared/ingest-spec.md:140 peker på 7aa53fc, ikke HEAD; samme
  setning ligger på :158/:160-161 etter bfa5a9b, som skrev om nettopp det
  kulepunktet + §4 title-raden. Konsumentens shared/-kopi ligger ett commit bak.
- De to oppstrøms-enumerasjonene er ikke samme mengde: fem stories vs. fem
  D-A-punkter, bare tre par binder. D-A#5 (hovedbok) har ingen story-etikett og
  faller utenfor pakken hvis den ratifiseres som beskrevet.

Målt mot fasit-bundelen: nominal gate (claimed 30000 <= nominal 90000.0) og
IR-invarianten (unit_cost 1.0 i [0.70, 1.40]) er byte-nøytrale; kostbaseline er
det eneste punktet som endrer fixturen hvis kravet blir ubetinget (§7:332-333
sier "two JSON files ... the only ground truth").

B1 ankret: = D4 fra OKF-runden, commons-halvdelen levert b641741, og det åpne
spørsmålet er vårt eget — klassen har 0 normative referanser i dag.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XYkLsRfSBBUjULS219Fy8X
2026-07-25 20:09:07 +02:00
docs/plan docs(plan): amendment-underlag — frossen tekst per køpunkt, med målt fasit-effekt 2026-07-25 20:09:07 +02:00
examples docs(examples): nav-golden fixture class — bundle → read-context goldens 2026-07-21 10:22:50 +02:00
skills/expert-reviewer feat(persona): build the shared expert-reviewer persona as a framework-neutral Agent Skill 2026-06-30 13:59:42 +02:00
.gitignore docs(plan): llm-ingestion-guard adoption — planned at future untrusted ingest boundaries 2026-07-16 07:38:37 +02:00
CONCEPT.md docs(shared): konsept-notat til norsk (Forgejo-publikum = norsk marked) 2026-06-26 21:31:02 +02:00
ingest-spec.md docs(spec): ingest-spec — land ratified D1 stamp model 2026-07-21 09:16:09 +02:00
method-spec.md docs(spec): method-spec §3 Step 1 — Q3 navigation contract (hierarchy) 2026-07-21 09:26:43 +02:00
README.md docs(spec): ingest-spec.md — normative ingest layer contract (I1) 2026-07-03 14:03:59 +02:00

README.md

shared/ — framework-neutral core

This directory holds the parts of the project that are independent of any AI agent framework and are meant to be shared, unchanged, between both reference implementations:

  • this repository — the method built on Microsoft Agent Framework (MAF);
  • a sibling repository (built later, in sequence) — the same method on the Claude Agents 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.

Contents (growing)

  • CONCEPT.md — the business concept, written for a non-specialist (e.g. a business developer at another company).
  • 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.
  • 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; shared/ stays pure data (each stack reads the JSON with its own loader).
  • 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. The sibling implementation is built from this spec alone, without reverse-engineering the reference code.
  • ingest-spec.md — the normative ingest specification, framework-neutral (same guard rule as the method spec): 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.

Rules

  • Nothing in here may import or depend on a specific agent framework. If it does, it does not belong in shared/.
  • Repo layout (decision R1, realized 2026-07-03): the shared core lives in its own repository, portfolio-optimiser-commons — the source of truth. Each implementation repo consumes it as a git subtree at this unchanged shared/ path (so tests and the PORTFOLIO_SHARED_ROOT default resolver are unaffected). Do not edit commons content anywhere else without syncing.

Subtree sync (pull-only — run from the consuming repo's root)

The remote is registered as commons (ssh://git@git.fromaitochitta.com/ktg/portfolio-optimiser-commons.git).

All edits land in commons first (clone it, commit, push there), then each consuming repo pulls them in:

git subtree pull --prefix=shared commons main --squash

Never run git subtree push from a consuming repo. Observed 2026-07-03: because this repo's history contains commits that create/delete the shared/ prefix, the push re-split leaked the consumer's entire history into commons (cleaned up by force-push the same day). Pull-only keeps commons the clean source of truth.

See the target picture for the full architecture: docs/plan/2026-06-26-maalbilde-agentic-loop.md.