# 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`](CONCEPT.md) — the business concept, written for a non-specialist
  (e.g. a business developer at another company).
- [`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.
- [`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; `shared/` stays pure data (each stack reads the JSON with its own loader).
- [`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.
  The sibling implementation is built from this spec alone, without reverse-engineering the
  reference code.

## 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`](https://git.fromaitochitta.com/ktg/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:

```sh
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`.