docs(shared): framework-neutral concept note + shared-core contract

First artifact in the framework-neutral shared core (R1 effectuated). CONCEPT.md
is a plain-language business description of the method for a non-specialist
audience; README.md documents the shared-core contract (consumed unchanged by
both the MAF impl and the future Claude Agents SDK sibling; extract to commons
repo via git subtree split when sibling work starts). English per the repo's
documentation-language convention + open-publish intent.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019any9zfGNNwWJPX5Zq2QRz

shared/CONCEPT.md

@@ -0,0 +1,79 @@
+# The Concept
+
+*A plain-language description of what this project is and why it matters — written for a
+non-specialist, e.g. a business developer at another company. Framework-neutral: it
+describes the method, not any particular implementation.*
+
+---
+
+## The problem
+
+Many organizations run a **portfolio of independent projects** at the same time —
+construction projects, IT services, infrastructure works, production lines. Inside *each
+individual* project sit hidden cost savings: a material that could be substituted, a
+specification that is needlessly conservative, a procurement contract that could be
+renegotiated. Finding them requires an experienced specialist to study that specific
+project in depth — and that expertise is expensive and scales poorly across a whole
+portfolio. So the savings are left on the table.
+
+Generative AI can suggest ideas, but a business developer immediately sees two obstacles:
+you cannot trust numbers a language model *guesses*, and the model does not know your
+industry's actual rules and experience. The concept is built precisely to remove these
+two obstacles.
+
+## How it works
+
+For each project, everything known about it is gathered — project documents, the
+discipline's assessment methodology, relevant professional literature, and the hard
+constraints (budget, what cannot change, regulatory requirements) — into a **curated,
+per-project knowledge base**. It is built on an open, vendor-neutral standard (Google's
+Open Knowledge Format), so it is portable and not locked to a single vendor.
+
+A team of AI agents reads this context, proposes concrete measures, and debates them
+against each other — one proposes, another critiques. But — and this is the heart of it —
+**the agents are never allowed to decide the value themselves.** Every number is sent to a
+separate, **deterministic calculation engine** (mathematical optimization plus risk
+simulation) that computes the actual saving. The AI proposes; the math decides. That is
+the trust anchor that separates this from "ask a chatbot."
+
+The measures that survive the calculation are presented to a **human domain expert** who
+issues a verdict: approve, improve, or reject.
+
+## What makes it valuable over time
+
+This is where the differentiation lies. The system **learns from the experts' verdicts.**
+There is almost always a gap between what a model *computes* and what an experienced
+specialist actually *approves* — because the expert knows how measures behave in practice,
+not just in theory. The system captures that gap and feeds it back, so the proposals get
+sharper on *your* organization's reality, not generic averages. The more verdicts, the
+better.
+
+And it respects how experts actually work: sometimes they respond on the spot, other times
+it takes days or weeks. The expert simply places their assessment into a **folder**, and
+the system picks it up whenever it arrives. No requirement for real-time, and no one has to
+be standing by.
+
+## What it is — and isn't
+
+It is a **purely technical framework**, not a finished compliance product. The
+organization that adopts it owns its own purpose, privacy, and governance; the framework
+only provides the technical preconditions (run locally, traceability on every proposal, no
+data leaving silently). It can run locally or in the cloud, and is published openly so
+others can adopt it.
+
+## Why it is built twice
+
+The same concept is built on **two different AI agent platforms** — Microsoft's Agent
+Framework and Claude's Agent SDK — on exactly the same example, so they can be compared
+fairly. This gives both an open reference others can copy, and an honest basis for judging
+which platform fits the task best.
+
+## Concretely
+
+Consider energy efficiency across a portfolio of buildings. Each building is a project with
+its own measure options (ventilation, lighting, insulation). The calculation engine
+computes the *modeled* saving for a package of measures under a budget. But an energy
+advisor knows that modeled and realized savings are rarely the same — behavior, measurement
+uncertainty, and interactions between measures create a gap. The expert's verdicts teach the
+system to close that gap over time. It is exactly in a field like this — where genuine
+expert judgment exists *beyond* pure calculation — that the concept comes into its own.

shared/README.md

@@ -0,0 +1,31 @@
+# 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).
+- *(planned)* the method specification, the example knowledge bundles (OKF / LLM-wiki),
+  the expert-reviewer persona, and the golden-suite of expected validator outcomes.
+
+## 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`.