feat(scaffold): S5 — D7 sibling scaffold: SDK dep, fail-fast startup contracts, CLAUDE.md

Claude Agent SDK verified against official docs + PyPI 2026-07-03 (0.2.110, CLI
bundled, offline import without API key). Contracts mirror method-spec §10/§4.1/§8:
data-source, model-map (per-profile default required), termination (positive caps),
binary feedback decision. TDD: tests written red-first; suite 14/14 green without
any API key; ruff + mypy --strict clean.

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

CLAUDE.md

@@ -0,0 +1,69 @@
+# portfolio-optimiser-claude
+
+## Kontekst
+Søsken-implementasjon (beslutning D7) av portfolio-optimiser-metoden på **Claude Agent SDK**:
+generisk, åpent Python-rammeverk som finner kostnadsbesparelser INNI hvert prosjekt i en
+portefølje. Bygges **fra metode-spec-en alene** (`shared/method-spec.md`) — aldri ved
+reverse-engineering av MAF-søskenet (`~/repos/portfolio-optimiser`). Program-planer
+(sesjonsplan S5–S12, sammenligningsprotokoll, frossent målbilde) bor i hovedrepoets
+`docs/plan/`. Løpende state: `STATE.md` (local-only).
+
+## Stack
+Python ≥3.10. **Claude Agent SDK** (`claude-agent-sdk` ≥0.2, verifisert 0.2.110 per
+2026-07-03: MIT-lisens, bundler Claude Code CLI — ingen separat installasjon; import og
+konstruksjon fungerer uten API-nøkkel, nøkkel trengs kun ved faktisk `query()`).
+Pakkehåndtering: `uv`. Pydantic for kontrakts-validering.
+
+## Konvensjoner
+- Type hints overalt; `mypy --strict`. `ruff` for lint+format. `pytest` for test.
+- **Testsuiten kjører uten API-nøkkel og uten nettverk** (invariant fra S5; håndhevet ved at
+  all kontrakts-/kontekst-logikk er ren config/fil-lag).
+- Modell-valg som konfig: `src/portfolio_optimiser_claude/data/model_map.json`
+  (rolle→Claude-modell-id per backend-profil, hver profil krever `default`; validert av
+  `contracts.py`). Modell-id-er verifiseres mot offisiell doc før endring.
+- SDK-primitiver (verifisert 2026-07-03): `query()`/`ClaudeSDKClient`, `ClaudeAgentOptions`
+  (`max_turns`, `max_budget_usd` — førsteklasses USD-tak), `AgentDefinition` (subagenter;
+  sub-felt er camelCase), `@tool` + `create_sdk_mcp_server` (in-process MCP), hooks
+  (`PreToolUse` med `permissionDecision: "deny"` for deterministisk gating). MERK:
+  `SessionStart`/`SessionEnd` finnes IKKE som Python-callback-hooks.
+- `shared/` er en **git subtree** av
+  [`portfolio-optimiser-commons`](https://git.fromaitochitta.com/ktg/portfolio-optimiser-commons)
+  (source of truth; remote `commons`). Synk er **PULL-ONLY**: endringer committes i commons og
+  hentes med `git subtree pull --prefix=shared commons main --squash`. ALDRI `git subtree push`
+  fra konsument — re-split lekker hele konsument-historikken inn i commons (observert + opprydd
+  i MAF-repoet 2026-07-03). Se `shared/README.md`.
+
+## Kommandoer
+- Sync: `uv sync`
+- Test: `uv run pytest`
+- Lint: `uv run ruff check .` + `uv run ruff format .`
+- Type: `uv run mypy src`
+
+## Arbeidsflyt (invarianter)
+- **Rent teknisk rammeverk:** deployer eier DPIA/ROS/behandlingsformål — kun tekniske
+  forutsetninger (lokal-only, provenance, ingen stille egress) + disclaimer.
+- **Metode-spec-en er normativ** (RFC 2119). Ærlighets-regelen (§1) er ufravikelig: ingen
+  artefakt påstår mer enn implementasjonen gjør; skriptede stand-ins merkes som det.
+- **Deterministisk validator obligatorisk + blokkerende** (§3 steg 4); golden-suiten
+  (`shared/examples/bygg-energi-mikro/golden.json`) er ENESTE fasit (§7).
+- **Load-bearing tester** (§11): hver søm bevises med en test som blir RØD når sømmen
+  detaches — grønn-men-død er feilmoden regelen finnes for.
+- **Stoppkriterier + budsjett-tak påkrevd ved oppstart** (§8; `contracts.py` fail-fast).
+  På kjørestien kommer USD-taket i tillegg via `ClaudeAgentOptions.max_budget_usd`.
+- **Kostnadsdisiplin (D6):** alt utvikles offline/deterministisk; den ENE ekte API-kjøringen
+  i programmet er S10 (mikro-bundle, billigste egnede modell — per model_map Haiku 4.5 —
+  harde tak, kost loggføres).
+- **STATE.md er local-only** (gitignored — repoet skal publiseres; STATE når aldri et
+  offentlig speil).
+
+## Communication patterns
+
+### Linking to local files
+
+When pointing to local files in responses, always use markdown link syntax with a descriptive name:
+
+- Use `[Human-friendly name](file:///absolute/path)` — never bare `file:///...` URLs or autolinks `<file://...>`.
+- Always use absolute paths. Never `~/` or relative paths.
+- For multiple files, render as a bullet list of named markdown links.
+
+Why: bare `file://` URLs only render the first as clickable across multiple lines. Named markdown links make each entry independently clickable and look cleaner.