feat(shared): S4 — re-introduce shared/ as subtree of portfolio-optimiser-commons

commons (ktg/portfolio-optimiser-commons @ 7d2b46c) is now the source of
truth for the framework-neutral shared core; this repo consumes it via
git subtree (--squash) at the unchanged shared/ path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AaQCFnfsh3tfq1VfzdJpoi

shared/README.md

@@ -0,0 +1,44 @@
+# 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, 2026-06-26):** the shared core lives here for now. When
+  work on the sibling repository begins, it will be extracted into its own repository
+  (e.g. `portfolio-optimiser-commons`) via `git subtree split`, and both implementation
+  repos will consume it. This defers cross-repo plumbing until it is actually needed.
+
+See the target picture for the full architecture: `docs/plan/2026-06-26-maalbilde-agentic-loop.md`.