Framework-neutral shared core of the portfolio-optimiser method: the normative specs, example bundles and golden fixtures vendored by both reference implementations.
Kjell Tore Guttormsen
3f18ca7c27
The question turned out not to be binary. Three distinct reference shapes are already in use across the specs, with different binding force: A artifact-name-as-ground-truth method-spec §7 :332-333 B directory convention + entries ingest-spec §11 :259-267 C informative catalogue link README :19 nav-golden has none of them. Verified: 0 hits in all five normative files (method-spec, ingest-spec, CONCEPT, README, SKILL). Two findings that constrain the option space: - method-spec never names a repo path at all (`grep -c 'examples/'` -> 0; the ten `/`-bearing tokens are in-bundle link syntax). A shape-B reference would be the first one in that document. - Elevating to §7 ground truth (O3) means rewriting two counting claims, not adding a sentence: §7 "two JSON files ... the only ground truth" and the §1 conformance clause 2 "on the shared example bundle" (singular). Also surfaced: nav-golden's serialization is not byte-pinned (nav-golden-hierarchy/README.md:31-33 says MAY) while the sister class ingest-golden is (:267, :280). Two conforming gates can disagree on the same fixture today, independent of whether the spec names the class. No normative text changed; no new text proposed. Ratification is the operator's. Amendment-underlag §8: corrected the verification-log check, which cited `grep -rn 'nav-golden' *.md` -> 0 hits. That command now returns 3 (all in the gitignored, non-normative STATE.md). The claim holds; the check was too wide. Re-aimed at the five normative files, and cross-linked to the new document. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XYkLsRfSBBUjULS219Fy8X |
||
|---|---|---|
| docs/plan | ||
| examples | ||
| skills/expert-reviewer | ||
| .gitignore | ||
| CONCEPT.md | ||
| ingest-spec.md | ||
| method-spec.md | ||
| 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: aSKILL.mdpersona prompt (energy-advisor / M&V role + the realization-gap methodology the validator cannot compute) and a canonicalreferences/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 unchangedshared/path (so tests and thePORTFOLIO_SHARED_ROOTdefault 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.