docs(repo): meet the org repo-standard gate — 0 ERROR

Ran `repo-standard` (v0.1.1, class `standalone`) and fixed everything it
flagged as ERROR, plus the WARN links that were genuinely dead.

README first screen:
- opening line is now byte-identical to the forge description, so
  description == catalog == README is machine-checkable (badges moved below).
- `## Install` (required for class `standalone`): clone + `uv sync`, stated as
  clone-only because the shared spec, persona skill and example bundles under
  `shared/` are read from the working tree at run time. `uv run pytest` named as
  the verification, with the fact that no CI runner exists said out loud rather
  than implied by a badge.
- `## Non-goals` (required): the five limits already binding in CLAUDE.md —
  not a compliance product, not a portfolio-level reallocator, not autonomous
  decision-making, not turnkey, not a model benchmark.

Dead relative links (measured, not guessed):
- `docs/plan/2026-07-10-sesjonsplan-fase2-6.md` pointed at
  `../2026-07-14-revisjonspakke-DF-DI.md` six times; the file sits in
  `docs/plan/`, not `docs/`. (The sibling `../review-2026-07.md` links are
  correct and untouched.)
- the Fase-1 spike brief linked repo-root-relative from
  `.claude/projects/…/`; re-anchored with `../../../`.

The one remaining README ERROR was a gate false positive: `checkInternalLinks`
resolves targets against `git ls-files`, which lists files only, so a link to a
directory can never resolve. `[shared/](shared/)` now points at
`shared/README.md` — a better target anyway, since that file carries the
pull-only subtree rule. Not fixed here: the classifier lives in another repo.

Remaining WARNs are all inside `shared/`, deliberately untouched: it is a
pull-only commons subtree, and the nav-golden files are byte-level fixtures
that gate `test_nav_golden_*` — four of them are OKF bundle-internal links,
and the `/etc/passwd` ones are the negative escape fixture doing its job.

Suite green: 630 passed, 4 skipped (markdown-only diff; no test touched).

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

.claude/projects/2026-06-23-fase1-derisk-spikes/brief.md

@@ -31,7 +31,7 @@ phase_signals:
 
 ## TL;DR
 
-**Refine** of the locked plan ([§Fase 1](docs/plan/2026-06-23-incremental-plan.md)) — same intent, narrowed to executable spike scope. Build four **throwaway** de-risk spikes (A–D) that convert the framework's most dangerous *documented-but-unverified* assumptions into *measured facts* before the Fase 2 vertical slice. Each spike has a falsifiable pass/fail from the plan's verification block. No new external research — reuse the research report's §15 implementation register. Runtime agent calls default to the **LOCAL profile** with hard token/round caps per D6.
+**Refine** of the locked plan ([§Fase 1](../../../docs/plan/2026-06-23-incremental-plan.md)) — same intent, narrowed to executable spike scope. Build four **throwaway** de-risk spikes (A–D) that convert the framework's most dangerous *documented-but-unverified* assumptions into *measured facts* before the Fase 2 vertical slice. Each spike has a falsifiable pass/fail from the plan's verification block. No new external research — reuse the research report's §15 implementation register. Runtime agent calls default to the **LOCAL profile** with hard token/round caps per D6.
 
 ## Intent
 
@@ -87,7 +87,7 @@ Four runnable spike modules (isolated so they are trivial to discard), each prod
 
 ## Research Plan
 
-No external research needed — the codebase and the existing research report ([docs/research/2026-06-23-prior-art-platform.md](docs/research/2026-06-23-prior-art-platform.md) §13 architecture, §15 implementation register, §15.3 footguns) plus this brief contain sufficient context for planning. The spikes themselves ARE the empirical de-risking. Any MAF API specifics (e.g. the exact current-version Python Group Chat termination API, U3) are confirmed inline via the `microsoft-learn` MCP at coding time rather than as a separate research pass.
+No external research needed — the codebase and the existing research report ([docs/research/2026-06-23-prior-art-platform.md](../../../docs/research/2026-06-23-prior-art-platform.md) §13 architecture, §15 implementation register, §15.3 footguns) plus this brief contain sufficient context for planning. The spikes themselves ARE the empirical de-risking. Any MAF API specifics (e.g. the exact current-version Python Group Chat termination API, U3) are confirmed inline via the `microsoft-learn` MCP at coding time rather than as a separate research pass.
 
 ## Open Questions / Assumptions
 

README.md

@@ -1,5 +1,7 @@
 # portfolio-optimiser
 
+Generic, open framework on Microsoft Agent Framework (MAF): multi-agent cost-saving proposals gated by a mandatory deterministic validator, with HITL learning.
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue.svg)](pyproject.toml)
 [![Built on Microsoft Agent Framework](https://img.shields.io/badge/built%20on-Microsoft%20Agent%20Framework-0078D4.svg)](https://github.com/microsoft/agent-framework)
@@ -10,6 +12,45 @@ generates candidate measures; a **mandatory deterministic validator** (solver +
 decides the numbers; domain experts judge the outcomes (human-in-the-loop); and the system
 **learns from their verdicts** across runs.
 
+## Install
+
+Python ≥3.10, with [`uv`](https://docs.astral.sh/uv/). The package is not published to a package
+index — install it from source:
+
+```bash
+git clone https://git.fromaitochitta.com/open/portfolio-optimiser.git
+cd portfolio-optimiser
+uv sync
+```
+
+Clone rather than install into an existing environment: the shared spec, the persona skill and the
+example bundles under [`shared/`](shared/README.md) are read from the working tree at run time.
+
+Verify the install by running the whole suite from the clean clone:
+
+```bash
+uv run pytest
+```
+
+There is no CI runner in this organization, so nothing runs that suite automatically — the command
+above is the verification.
+
+## Non-goals
+
+- **Not a compliance product.** It ships the technical prerequisites — local-only operation,
+  provenance on every proposal, no silent data egress — and stops there. Processing purpose, DPIA
+  and risk assessment stay with the deploying organization.
+- **Not a portfolio-level reallocator.** It finds savings *inside* each project. Moving budget
+  between projects, ranking projects against one another and portfolio governance sit above the
+  method and are out of scope.
+- **Not autonomous decision-making.** The deterministic validator can only block; approving a
+  measure is a domain expert's call (human-in-the-loop), and the framework implements nothing on
+  the agents' say-so.
+- **Not a turnkey vertical solution.** The aim is a generic core with explicit extension points
+  (data sources, cost models, personas) — not the last 10% of any one domain.
+- **Not a model benchmark.** The end-to-end proof runs offline against a scripted stand-in client:
+  it shows that the loop closes, not how well a given LLM proposes or judges.
+
 > **Status:** the full 8-step agentic loop is wired and proven with load-bearing tests, and the
 > end-to-end proof is an **offline simulation** with a scripted stand-in client — no live-model
 > run yet. The **ingest layer** (real data sources) is implemented — file/CSV and SQL on both
@@ -89,7 +130,7 @@ when the seam is detached, so the loop cannot silently degrade into theater.
 
 ## How it is set up
 
-- **One shared, framework-neutral core** ([`shared/`](shared/), a git subtree of
+- **One shared, framework-neutral core** ([`shared/`](shared/README.md), a git subtree of
   [`portfolio-optimiser-commons`](https://git.fromaitochitta.com/ktg/portfolio-optimiser-commons)):
   the business concept, the normative [method spec](shared/method-spec.md) and
   [ingest spec](shared/ingest-spec.md), the expert-reviewer persona as an Agent Skill, and an

docs/plan/2026-07-10-sesjonsplan-fase2-6.md

@@ -6,7 +6,7 @@
 > **Revidert 2026-07-14:** beslutningene D-F–D-I (kunnskapsinnholdsmodell, OKF-modul/fabrikk/evaluator,
 > oppsett/brukervennlighet, verdibevis/kostnadsstyring) ble truffet i operatør-samtale og er flettet inn
 > her (§2-oppføringer + nye sesjoner S3.5/S3.6/S5.4 + S5.3-utvidelse); fasit i
-> [revisjonspakke D-F–D-I](../2026-07-14-revisjonspakke-DF-DI.md).
+> [revisjonspakke D-F–D-I](2026-07-14-revisjonspakke-DF-DI.md).
 > Funn-referanser (F1–F14, P1–P6, U-1–U-4) peker til [reviewen](../review-2026-07.md).
 > **Beslutnings-sesjonene D-A–D-E er fortsatt ÅPNE (operatør-kø):** bygg-sesjoner gated på dem
 > starter ikke før beslutning foreligger; **S2.0/S2.1/S2.5 er byggbare NÅ** (ingen
@@ -91,12 +91,12 @@ UTENFOR dette repoets sesjoner; flagges i hver berørt sesjon.
 
 **D-F–D-I — BESLUTTET 2026-07-14** (operatør-samtale, intensjonsanalyse). Til forskjell fra D-A–D-E
 over er disse fire allerede avgjort; fasit-protokoll + innplassering i
-[revisjonspakke D-F–D-I](../2026-07-14-revisjonspakke-DF-DI.md). Frosne dokumenter er IKKE endret ennå
+[revisjonspakke D-F–D-I](2026-07-14-revisjonspakke-DF-DI.md). Frosne dokumenter er IKKE endret ennå
 — amendments skjer via commons (PULL-ONLY) i egne økter. Oppføringene under oppsummerer beslutningen +
 hva den blokkerer/åpner (ikke hele fasiten).
 
 ### D-F — Kunnskapsinnholdsmodell `[BESLUTTET 2026-07-14]`
-- **Status:** BESLUTTET 2026-07-14. Fasit: [revisjonspakke §1](../2026-07-14-revisjonspakke-DF-DI.md).
+- **Status:** BESLUTTET 2026-07-14. Fasit: [revisjonspakke §1](2026-07-14-revisjonspakke-DF-DI.md).
 - **Kjerne:** ny delt innholdsmodell i commons (kunnskapstyper tiltaksmønstre/erfaringsnotater/faglige
   råd, alle med påkrevd kildebelegg) — KUN lesestoff for forslagsstilleren, validatorens regler urørt.
   Streng separasjon fra dommene (bibliotek via `bundle_context`; korreksjoner KUN via ExpeL-folden).
@@ -108,7 +108,7 @@ hva den blokkerer/åpner (ikke hele fasiten).
   produksjonsjobb, ikke del av S3.5. Fabrikk-avhengige deler venter på toolkit-repoet (D-G).
 
 ### D-G — OKF: felles modul, fabrikk, evaluator `[BESLUTTET 2026-07-14]`
-- **Status:** BESLUTTET 2026-07-14. Fasit: [revisjonspakke §2](../2026-07-14-revisjonspakke-DF-DI.md)
+- **Status:** BESLUTTET 2026-07-14. Fasit: [revisjonspakke §2](2026-07-14-revisjonspakke-DF-DI.md)
   (+ kryssrepo-inventar §0.2).
 - **Kjerne:** standard-kompatibel OKF (F4/`/`-lenkeformen rettes — forsterker **D-A pkt. 3**), egne
   utvidelser dokumenteres eksplisitt som utvidelser. **Felles OKF-kode JA** (endrer D7s «from spec
@@ -120,7 +120,7 @@ hva den blokkerer/åpner (ikke hele fasiten).
   som blokkerer fabrikk-avhengige deler av D-F/D-H. Guard forblir eget sikkerhets-repo (avhengighet).
 
 ### D-H — Oppsett og brukervennlighet `[BESLUTTET 2026-07-14]`
-- **Status:** BESLUTTET 2026-07-14. Fasit: [revisjonspakke §3](../2026-07-14-revisjonspakke-DF-DI.md).
+- **Status:** BESLUTTET 2026-07-14. Fasit: [revisjonspakke §3](2026-07-14-revisjonspakke-DF-DI.md).
 - **Kjerne:** oppsett gjøres ALLTID av et lite team (teknisk + fag); leveransen er en **oppskrift**
   (dokumentert prosess), ikke en veiviser (B9-onboarding + guidet dom-kommando FORKASTET). Fagpersonen
   leverer filer i egne formater — aldri skjema/JSON; **fabrikken** (D-G) AI-oversetter fri-format-dommer
@@ -131,7 +131,7 @@ hva den blokkerer/åpner (ikke hele fasiten).
   dom-oversettelse + demo-sti er fabrikk-avhengige (D-G/T0), blokkert til toolkit finnes.
 
 ### D-I — Verdibevis + kostnadsstyring `[BESLUTTET 2026-07-14]`
-- **Status:** BESLUTTET 2026-07-14. Fasit: [revisjonspakke §4](../2026-07-14-revisjonspakke-DF-DI.md).
+- **Status:** BESLUTTET 2026-07-14. Fasit: [revisjonspakke §4](2026-07-14-revisjonspakke-DF-DI.md).
 - **Kjerne:** publiserings-påstand = **nivå 2** (realistisk case, modellerte tall, aldri salgsspråk over
   beleggsnivået); nivå 3 (ekte pilot) er åpen invitasjon. **Verdirapport per kjøring** (kjerne):
   hovedbok-basert modellert→korrigert→realisert, målprogresjon, tallfestet læringseffekt, kost-mot-verdi.