docs(plan): utrulling D-F–D-I — sesjonsplan (D-F–D-I i §2, S3.5/S3.6/S5.4, graf+T0), roadmap-revisjonsblokk, commons-amendment-utkast (Step-1-analyse: NEI → minimal amendment), toolkit-repo-brief

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

docs/plan/2026-07-14-commons-amendment-utkast.md

@@ -0,0 +1,488 @@
+# Commons-amendment-utkast — kunnskapsinnholdsmodell + utvidelses-policy (2026-07-14)
+
+> **Status:** UTKAST til operatør-godkjenning. Kilde: [revisjonspakke D-F–D-I](2026-07-14-revisjonspakke-DF-DI.md)
+> §1 (D-F) + §2 (D-G). Dette dokumentet er en **komplett, innlimings-klar** amendment til de to
+> delte spec-ene i `portfolio-optimiser-commons` (`method-spec.md` + `ingest-spec.md`). Ingenting er
+> committet i commons, og `shared/` i dette repoet er **ikke** rørt — overføringen er manuell,
+> PULL-ONLY, i egen økt ETTER at operatøren har godkjent teksten under.
+>
+> **Provenance:** amendment-tekst = AI-forfattet (Fable 5, 2026-07-14), forankret i faktisk lest
+> spec + kode (`method-spec.md`, `ingest-spec.md`, `okf.py`, `dimension.py`,
+> `test_method_spec_loadbearing.py`). Beslutningene bak (D-F/D-G) er operatørens, protokollert i
+> revisjonspakka. Spec-teksten er engelsk (RFC-2119, framework-nøytral — samme regel som resten av
+> de delte spec-ene, håndhevet av `test_method_spec_is_framework_neutral`). Rammetekst er norsk.
+
+## 0. Slik brukes utkastet
+
+Fire leveranser, i den rekkefølgen operatøren bør lese dem:
+
+1. **§1 — Innholdsmodell-amendment til `method-spec.md`** (engelsk spec-tekst i innlimings-blokker):
+   tre nye konsepttyper, separasjonsregelen, dimensjonskatalog-kontrakten, cross-check-utvidelser.
+2. **§2 — Bibliotek-materialisering som ny ingest-kildefamilie `library`** (eget under-utkast til
+   `ingest-spec.md`, med korrekt §-referanse).
+3. **§3 — Trinnvis-lesing-analysen** (revisjonspakka §6 nøkkelantakelse): kan sammendrag-først
+   spesifiseres UTEN å endre `method-spec.md` §3 Step 1s render-kontrakt? **Eksplisitt JA/NEI +
+   begrunnelse forankret i siterte spec-linjer.**
+4. **§4 — Utvidelses-policy** (D-G pkt. 1) og **§5 — Konsekvens-liste** (spec-integrity-test,
+   D7-speiling, golden-suite).
+
+Hver engelsk innlimings-blokk er avgrenset med `--- BEGIN SPEC INSERT ---` / `--- END SPEC INSERT ---`
+og merket med nøyaktig hvilken §-plassering den hører til, slik at overføringen til commons er
+mekanisk. Tabeller er ekte markdown (ikke code-fenced) så de rendrer i commons uendret.
+
+---
+
+## 1. Innholdsmodell-amendment til `method-spec.md`
+
+**Plassering:** ny toppseksjon `## 13. The knowledge library (content-model extension)` (bakerst, så
+eksisterende §-numre ikke forskyves — `_REQUIRED_MARKERS` i integrity-testen er presence-asserts, se
+§5), pluss tre målrettede inserts i eksisterende seksjoner (§2, §10, §12) og render-kontrakt-endringen
+i §3 Step 1 (den siste hører til §3-analysen, se **§3** under).
+
+### 1.1 Ny toppseksjon — de tre konsepttypene + separasjonsregelen
+
+Rasjonale (norsk, ikke del av innlimingen): D-F pkt. 1 krever kunnskapstyper for *tiltaksmønstre,
+erfaringsnotater, faglige råd*, alt med **påkrevd kildebelegg**. D-F pkt. 3 krever **streng separasjon
+fra dommene**: biblioteket flyter via `bundle_context`, korreksjonene KUN via den gatede folden — aldri
+blandet. Typene er kontekst-lag-innhold (`method-spec.md` §2: "This layer holds project documents,
+methodology, verified literature, constraints..."), altså **kun lesestoff for forslagsstilleren** (D-F
+pkt. 2 — validatorens regler røres ikke).
+
+--- BEGIN SPEC INSERT (method-spec.md → new `## 13.`) ---
+
+## 13. The knowledge library (content-model extension)
+
+The context layer (§2) MAY carry a **knowledge library**: curated, source-attested domain
+knowledge about how savings are found within a dimension (§13.3), shared across the projects of a
+portfolio and materialized into each project bundle (the ingest `library` source family — ingest
+spec §4a). The library is **read-only input to the proposer**: it feeds hypothesis generation as
+context, and it MUST NOT alter the deterministic validator's rules (§4), which remain the sole
+authority over the numbers. Coupling the library to the validator is explicitly out of scope for
+this version.
+
+Three library concept types are defined. Each is an ordinary OKF concept file (§2, §3 Step 1) — the
+only additions are required frontmatter fields:
+
+- **`type: measure-pattern`** — a reusable cost-saving *pattern*: what the measure is, the
+  parameters that drive its modelled saving, and the realization caveats a proposer should know.
+- **`type: experience-note`** — an operational *experience* (the writable part of tacit knowledge):
+  what happened when such a measure was carried out, and the gotchas. Genuinely tacit knowledge is
+  NOT forced here — it is captured by the verdicts' rationale prose (§4), the learning loop's
+  existing channel.
+- **`type: expert-advice`** — an expert *heuristic or recommendation* scoped to a dimension.
+
+**Required frontmatter (all three types):**
+
+| Field | Rule |
+|---|---|
+| `type` | One of `measure-pattern`, `experience-note`, `expert-advice`. |
+| `title` | Single-line human-readable title (the `## {type}: {title}` heading, §3 Step 1). |
+| `description` | A **single-line** summary of the file — this is the one-line summary the read-context's summary tier renders (§3 Step 1, the library-tier rule). REQUIRED and non-empty. |
+| `dimension` | The catalog dimension `id` (§13.3) this knowledge is scoped to. MUST match a catalog entry; an unknown dimension is a fail-fast error (§13.3). |
+| `sources` | The source attestation: a non-empty list of citations, each identifying a verifiable source (a reference plus a locator — URL, document id, or file+span). A library file with an **empty or missing `sources`** MUST be rejected at materialization (§13.2). |
+| `provenance` | Who authored the file and its verification status (e.g. machine-authored-with-source-verification vs. expert-authored). Machine-authored content MUST be labelled as such (§1 honesty rule). |
+
+`tags` and `timestamp` are OPTIONAL and follow the existing bundle convention. Unknown frontmatter
+fields are preserved (§3 Step 1, OKF robustness rule).
+
+**Source attestation (normative).** Every library concept file MUST carry at least one verifiable
+source in `sources`. This mirrors the provenance discipline of §9 ("at least one citation into the
+source documents"): unsourced domain claims MUST NOT enter the library. Enforcement is fail-fast at
+materialization (ingest spec §4a/§8a), never a runtime check inside the loop.
+
+### 13.1 The separation rule (unwaivable)
+
+The knowledge library and the verdict layer reach the hypothesis prompt through **two disjoint
+carriers that are never crossed**:
+
+- Library files (`measure-pattern`, `experience-note`, `expert-advice`) are context-layer content.
+  They reach the prompt **ONLY** via context rendering (§3 Step 1's read-context) — **never** via
+  the experience fold. They are not `type: verdict`, so seeding (§3 Step 1) never turns them into
+  store entries, and retrieval never ranks over them.
+- Prior verdicts reach the prompt **ONLY** via the gated experience fold (§3 Step 1) — **never** via
+  context rendering (the existing verdict-layer exclusion). This is unchanged.
+
+The two directions are symmetric and both load-bearing: an organisation's realization-rate
+corrections (verdicts) MUST NOT leak into the read-context, and library knowledge MUST NOT be
+injected as if it were an approved verdict. Conflating the carriers would either re-leak the gated
+learning signal or inject un-gated "approved" knowledge around the promotion gate (§6) — the
+self-contamination the layer separation exists to prevent (§2).
+
+--- END SPEC INSERT ---
+
+### 1.2 Dimensjonskatalog-kontrakten (D-F pkt. 5)
+
+Rasjonale (norsk): D-F pkt. 5 krever en **dimensjonskatalog som konfig**, skjema-validert fail-fast,
+med feltene *id, label, allowed_measure_types, allowed_code_prefixes*. Dette er **eksakt** den
+eksisterende `Dimension`-modellen (`src/portfolio_optimiser/dimension.py`) — amendmenten løfter den fra
+"konstrueres kun i tester" (revisjonspakka §0 F-INT-1) til en spec'et startup-kontrakt, uten å endre
+feltene. Katalogen hører til startup-kontrakt-disiplinen i §10 ("ALL configuration MUST be
+schema-validated fail-fast at startup").
+
+--- BEGIN SPEC INSERT (method-spec.md → new `### 13.3` under §13, and an §10 cross-reference) ---
+
+### 13.3 The dimension catalogue (startup contract)
+
+A **dimension** is one cost axis a project is reduced along (energy, paving, ...). A conforming
+implementation MUST define a **dimension catalogue**: configuration, schema-validated fail-fast at
+startup (§10), listing the dimensions the run recognises. Each entry:
+
+| Field | Rule |
+|---|---|
+| `id` | Stable dimension identifier (string). Library files reference it via `dimension:` frontmatter (§13). |
+| `label` | Human-readable label; non-empty. |
+| `allowed_measure_types` | The set of `measure_type` values that belong to this dimension. |
+| `allowed_code_prefixes` | The set of affected-code prefixes constraining the dimension; MAY be empty (no code constraint). |
+
+**Scoping gate (normative):** a candidate measure *belongs* to a dimension iff its `measure_type` is
+in `allowed_measure_types` **and** either `allowed_code_prefixes` is empty **or** at least one
+affected code starts with an allowed prefix. *(reference: `dimension.admits`.)*
+
+**Catalogue reference (normative):** every library file's `dimension:` MUST resolve to a catalogue
+`id`; a library file scoped to an unknown dimension is a fail-fast materialization error (ingest
+spec §4a). The framework SHIPS an example catalogue (the energy dimension); the deploying
+organisation owns its own catalogue.
+
+--- END SPEC INSERT ---
+
+--- BEGIN SPEC INSERT (method-spec.md → append one bullet to `## 10. Startup contracts`) ---
+
+- the dimension catalogue (§13.3), when the run uses a knowledge library — each entry REQUIRING
+  `id`, `label`, and `allowed_measure_types` (with `allowed_code_prefixes` defaulting to empty).
+
+--- END SPEC INSERT ---
+
+### 1.3 §2-insert (peker fra arkitektur-seksjonen) + §12 cross-check-rader
+
+Rasjonale (norsk): §2 lister kontekst-lagets innhold; den bør nevne biblioteket eksplisitt så
+separasjonsregelen er synlig der de tre lagene defineres. Og §12 cross-check-tabellen er
+**completeness-håndhevet** av integrity-testen (`test_spec_documents_every_contract_field` — hvert
+felt koden konsumerer må stå i spec-en som `` `felt` ``). Når D-F bygges vil koden konsumere de nye
+feltene; radene under sikrer at test 3 forblir grønn da (se §5).
+
+--- BEGIN SPEC INSERT (method-spec.md → append to the context-layer bullet in `## 2.`) ---
+
+The context layer MAY additionally carry a **knowledge library** (§13): source-attested
+`measure-pattern` / `experience-note` / `expert-advice` files. Like all context-layer content the
+library reaches the prompt only by navigation/rendering (§3 Step 1), never through the experience
+fold — and, symmetrically, verdicts never reach it through rendering (§13.1).
+
+--- END SPEC INSERT ---
+
+--- BEGIN SPEC INSERT (method-spec.md → append rows to the `## 12. Cross-check table`) ---
+
+| Field | Contract | Section |
+|---|---|---|
+| `description` | library concept frontmatter (summary tier) | §13, §3 Step 1 |
+| `dimension` | library concept frontmatter / dimension catalogue reference | §13, §13.3 |
+| `sources` | library concept frontmatter (source attestation) | §13 |
+| `provenance` | library concept frontmatter | §13 |
+| `id`, `label` | dimension catalogue entry | §13.3, §10 |
+| `allowed_measure_types`, `allowed_code_prefixes` | dimension catalogue entry | §13.3 |
+| `measure-pattern`, `experience-note`, `expert-advice` | knowledge-library OKF types | §13 |
+
+--- END SPEC INSERT ---
+
+> Merk (norsk): `description`, `type` og `measure_type` er allerede i §12; radene over er additive og
+> peker de NYE bruksstedene. Ved innliming: slå `description`-raden sammen med den eksisterende hvis
+> commons foretrekker én rad per feltnavn (integrity-testen krever bare at `` `description` ``
+> finnes, ikke antall rader).
+
+---
+
+## 2. Bibliotek-materialisering som ingest-kildefamilie `library` (`ingest-spec.md`)
+
+**Plassering:** ny kildefamilie `type: "library"` i `ingest-spec.md` §4 (polymorf på `source.type`,
+ved siden av `file`/`sql`/`http`), pluss en materialiserings-regel i §5 og en gate-regel i §8. Skrevet
+som eget under-utkast med korrekt §-referanse, jf. oppdraget.
+
+Rasjonale (norsk): D-F pkt. 4 sier det delte dimensjonsbiblioteket **materialiseres inn** i hver
+prosjekt-bundle via ingest-mønsteret (`generated: true`, manifest-ref, re-materialisering eier egne
+filer) — **ikke** kryssbundle-lenker (navigasjonen forblir flat/same-dir), **ikke** manuell
+duplisering. Ingest-spec §1 er allerede rammen: "data reaches the model ONLY via OKF bundles ...
+materializes the extract as a bundle". `library` er en ny kilde i den rammen. Den skiller seg fra
+`file`/`sql` på ett punkt: den materialiserer **kuraterte kunnskaps-konseptfiler** (prosa med
+frontmatter), ikke rader i en tabell — parallelt med hvordan `http` har sin egen body-render-regel.
+
+--- BEGIN SPEC INSERT (ingest-spec.md → new `### 4a. The `library` source family` under §4) ---
+
+### 4a. The `library` source family (extension)
+
+`type: "library"` materializes a **curated dimension library** (method spec §13) into a project
+bundle: shared, source-attested `measure-pattern` / `experience-note` / `expert-advice` files. It
+reuses the whole ingest contract (deterministic, zero model calls §1; provenance stamping §7;
+index generation §6; replacement semantics §3/§5). It exists so shared cross-project knowledge is
+**materialized in**, not cross-linked and not hand-duplicated (navigation stays flat/same-dir, OKF
+§3 Step 1 rule).
+
+**`source` fields** (in addition to the common `id`, §4):
+
+- Field `root`: the directory the curated library entries resolve against. Path resolution MUST be
+  boundary-checked against `root`, fail-closed (the OKF path rule) — an extraction can never read
+  outside the catalogue.
+
+**`extractions` — each entry** for a `library` source (all required):
+
+| Field | Meaning |
+|---|---|
+| `id` | Unique within the manifest, matching `[a-z0-9][a-z0-9-]*`; names the generated file (`library-{id}.md`, §5a). |
+| `title` | Single-line title; becomes the `title` frontmatter and the index link label (§6). |
+| `query` | A relative path (within `root`) to one curated library entry (a markdown file with frontmatter). |
+| `okf_type` | The generated file's OKF `type`. MUST be one of `measure-pattern`, `experience-note`, `expert-advice` (case-insensitive) and MUST NOT be `verdict` (§3 verdict-layer reservation). |
+| `dimension` | The dimension catalogue `id` (method spec §13.3) the entry is scoped to. Stamped as the generated file's `dimension` frontmatter. |
+| `max_rows` | Required positive integer cap; for `library`, the cap on entries drawn from a single curated file (§8). |
+
+**Source attestation is enforced here (normative).** A curated entry whose frontmatter carries an
+empty or missing `sources` list (method spec §13) MUST be rejected fail-fast at manifest/source
+validation — the machine-generated library never ships unsourced domain claims. This is the
+content model's teeth at ingest time, mirroring §8's other fail-fast caps.
+
+--- END SPEC INSERT ---
+
+--- BEGIN SPEC INSERT (ingest-spec.md → new `### 5a. `library` materialization` under §5) ---
+
+### 5a. `library` materialization (deterministic)
+
+For a `library` source, each extraction produces one concept file named `library-{extraction id}.md`
+(the `library-` prefix keeps the namespace disjoint from `index.md`, `ingest-*`, and
+`promoted-verdict-*`, §3). Materialization is deterministic and takes the same three explicit inputs
+as §5 (manifest, target bundle, `ingested_at`).
+
+- **Frontmatter** — the curated entry's own OKF frontmatter (`type` = the extraction's `okf_type`,
+  plus `title`, `description`, `dimension`, `sources`, `provenance` per method spec §13), extended
+  with the ingest provenance layer (§7): `source_system`, `source_query`, `ingested_at`,
+  `ingest_manifest`, `generated: true`. The provenance layer is ADDITIVE — it never overwrites the
+  curated `description`/`sources`/`provenance` fields (two separate contracts, never mixed, §7).
+- **Body rendering** — the curated entry's markdown body verbatim (LF-only, exactly one trailing
+  newline). Unlike `file`/`sql` (a table) or `http` (a fenced block), a library entry is already
+  authored prose; it is carried through unchanged.
+- **Replacement semantics (§3/§5):** library files carry the ingest stamp, so re-materialization
+  replaces EXACTLY the ingest-owned files and MUST NOT touch curated or promoted files. A
+  `library-{id}.md` collision with an unstamped existing file MUST fail — never overwrite curated
+  content.
+- **Index generation (§6):** each generated file gets one index cross-link
+  `- [{title}](library-{id}.md)`, preserving all curated and promoted links verbatim.
+
+--- END SPEC INSERT ---
+
+--- BEGIN SPEC INSERT (ingest-spec.md → cross-check table `## 12.`, append rows) ---
+
+| Field | Contract | Section |
+|---|---|---|
+| `root` | manifest source (`library`) | §4a |
+| `dimension` | manifest extraction (`library`) / generated frontmatter | §4a, §5a |
+| `okf_type` | manifest extraction (`library`, restricted set) | §4a, §3 |
+
+--- END SPEC INSERT ---
+
+> Merk (norsk): `root`, `title`, `query`, `okf_type`, `max_rows`, `id` finnes allerede i §12
+> (delt med `file`/`sql`/`http`); kun de genuint nye radene (`root` for library-source, `dimension`)
+> er additive. `library` arver §11-load-bearing-sømmene (provenance-stamping, navigerbarhet,
+> verdict-reservasjon, re-ingest-lag-sikkerhet) uendret — en ny golden-case
+> `examples/ingest-golden-library/` legges til (endrer ikke `file`/`sql`-goldens; se §5).
+
+---
+
+## 3. Trinnvis-lesing-analysen (revisjonspakka §6 nøkkelantakelse)
+
+**Spørsmål (revisjonspakka §6):** kan sammendrag-først / fulltekst-ved-behov (D-F pkt. 6)
+spesifiseres UTEN å endre `method-spec.md` §3 Step 1s render-kontrakt — «index body + hver konseptfil
+som `## {type}: {title}`-seksjon»?
+
+### 3.1 Konklusjon: **NEI** — det krever en minimal, bakoverkompatibel Step-1-amendment.
+
+Ikke gjettet — forankret i to siterte spec-linjer og render-koden.
+
+**Bevis 1 — render-kontrakten mandaterer full body per konseptfil.** `method-spec.md` §3 Step 1:
+
+> «The rendered read-context is the index body (the summary) followed by each non-index concept file
+> as a `## {type}: {title}` section; empty sections are dropped.» (method-spec.md:76–77)
+
+Referanse-implementasjonen fyller den seksjonen med **hele** filkroppen — `bundle_context` i
+`okf.py:150-151`:
+
+> `title = f.frontmatter.get("title", f.name).strip('"')`
+> `sections.append(f"## {f.type or 'document'}: {title}\n{f.body}")` — `f.body` er hele body.
+
+Med 15–30 tiltak i biblioteket (D-F pkt. 7) er «render hver konseptfil sin fulle body» **nettopp**
+prompt-drukningen D-F pkt. 6 avviser («Dagens 'render alt navigert' skalerer ikke»). Å rendre
+sammendrag først (én linje per fil) og full tekst kun for et utvalg er per definisjon *ikke* det
+kontrakten sier i dag → kontrakten må endres.
+
+**Bevis 2 — den eneste alternative bæreren for «fulltekst ved behov» er forbudt.** «Ved behov»
+antyder at agenten henter full tekst ved forespørsel. Men et query-time retrieval-verktøy mot bundelen
+er **eksplisitt forbudt** i samme Step 1:
+
+> «Prior verdicts reach the hypothesis prompt ONLY via the gated experience fold below — never via
+> context rendering, and **never via a query-time retrieval tool pointed at the bundle** (which would
+> re-leak the verdict layer).» (method-spec.md:78–81)
+
+Forsterket, arkitektur-definerende, i `ingest-spec.md` §1:
+
+> «The method spec (§3 Step 1) forbids query-time retrieval against the bundle. ... **data reaches
+> the model ONLY via OKF bundles** ... not RAG, not live lookups inside the agent loop, no retrieval
+> tools in the run path.» (ingest-spec.md:21–25)
+
+Så «fulltekst ved behov» kan **ikke** realiseres som et agent-kalt oppslagsverktøy. Det etterlater
+kun én lovlig mekanisme: et **deterministisk, pre-run utvalg** av hvilke filer som får full body —
+og det er nettopp en endring av render-kontrakten.
+
+**At det finnes presedens** (som gjør amendmenten liten, ikke prinsipielt ny): `bundle_context` har
+allerede et deterministisk `dimension`-filter (`okf.py:133, 146-149`) — «only concept files whose
+frontmatter `dimension` matches ... are rendered». Det beviser at arkitekturen allerede tåler et
+deterministisk pre-run-utvalg over hvilke filer som rendres, uten retrieval-verktøy. (Sidefunn: det
+filteret finnes i KODEN, men står ikke i method-spec §3 Step 1 i dag — en udokumentert utvidelse
+amendmenten samtidig bør folde inn i spec-en, jf. utvidelses-policyen §4.)
+
+### 3.2 Foreslått minimal Step-1-amendment (in-place i §3 Step 1)
+
+Endrer KUN seksjons-**innholdet** for bibliotek-tier-filer; beholder index-først, `## {type}: {title}`-
+overskriften, verdict-eksklusjonen og no-retrieval-invarianten. **Default (ingen bibliotek-tier-filer)
+er byte-identisk med dagens oppførsel** — så eksisterende bundler (f.eks. `bygg-energi-mikro`) rendres
+uendret og eksisterende tester forblir grønne (§5).
+
+--- BEGIN SPEC INSERT (method-spec.md → REPLACE the render bullet in §3 Step 1) ---
+
+- The rendered read-context is the index body (the summary) followed by each non-index concept file
+  as a `## {type}: {title}` section. A **library-tier** concept file (§13:
+  `measure-pattern` / `experience-note` / `expert-advice`) contributes only its single-line
+  `description` frontmatter as the section body by default — the **summary tier**, one line per
+  library file, so the library can grow large without prompt-drowning. Its **full body** is rendered
+  ONLY for the bounded subset chosen by a DETERMINISTIC pre-run selector (e.g. the candidate's
+  dimension, §13.3) — never by a query-time retrieval tool pointed at the bundle (the no-retrieval
+  invariant above). Non-library concept files render their full body as before. Empty sections are
+  dropped. *(reference: with no library-tier files present, this is byte-identical to rendering
+  every concept file's full body — the pre-existing behaviour.)*
+
+--- END SPEC INSERT ---
+
+> Norsk presisering: «deterministisk pre-run selector» = samme klasse som det eksisterende
+> `dimension`-filteret (kandidatens dimensjon avgjør hvilke bibliotekfiler som får full body).
+> Ingen ny modell-runde, intet oppslagsverktøy, ingen ny løkke — utvalget skjer FØR generering, på
+> IR-projeksjonens kandidat-features (som allerede er tilgjengelig pre-hypotese, §3 Step 1 fold).
+> Verdict-eksklusjonen er urørt: bibliotek-tier er en delmengde av `context_files` (aldri
+> `type: verdict`), så `test_bundle_context_excludes_verdict_layer` + empty-store-kontrollen forblir
+> røde-ved-detach som før.
+
+---
+
+## 4. Utvidelses-policy (D-G pkt. 1)
+
+**Plassering:** ny normativ note, enten som `### 2a. Relationship to Google OKF v0.1` i `method-spec.md`
+§2, eller som delt avsnitt i begge spec-enes §1. Kort, normativ.
+
+Rasjonale (norsk): D-G pkt. 1 — «standard-kompatibel»; egne utvidelser (innboks-konseptet,
+ingest-sikkerhet, evaluator-felt) dokumenteres **eksplisitt som utvidelser** av Google OKF v0.1 og
+**pensjoneres** hvis standarden senere dekker dem. Ingen permanent fork.
+
+--- BEGIN SPEC INSERT (method-spec.md → new `### 2a. Relationship to Google Open Knowledge Format v0.1`) ---
+
+### 2a. Relationship to Google Open Knowledge Format v0.1
+
+The bundle format is **Google Open Knowledge Format (OKF) v0.1**. This method adds capabilities ON
+TOP of the base format; each such capability is a **local extension**, not part of the standard, and
+MUST be documented as one:
+
+- the **verdict layer** and the **promotion gate** (§2, §6): `type: verdict` files, the
+  `promoted-verdict-*` filename namespace, and the neutral-label index rule;
+- the **inbox/outbox folder contract** (§5): the async long-loop file interface;
+- the **ingest provenance layer** and the **security frame** (ingest spec §7–§9):
+  `generated`/`ingest_manifest`/`source_system`/`source_query`/`ingested_at`, and the network
+  opt-in;
+- the **knowledge library** and the **dimension catalogue** (§13);
+- **evaluator fields** (future work): any conformance/sufficiency scoring frontmatter a bundle
+  evaluator introduces.
+
+**Retirement rule (normative):** if a future OKF version standardises an equivalent of a local
+extension, the implementation MUST migrate to the standard mechanism and RETIRE the local extension —
+no permanent divergence from the format. Extensions MUST NOT change the meaning of any base-format
+field; they only add reserved types, reserved filename namespaces, and additive frontmatter, all of
+which base-format consumers preserve as unknown fields.
+
+--- END SPEC INSERT ---
+
+---
+
+## 5. Konsekvens-liste
+
+### 5.1 Spec-integrity-testen (`tests/test_method_spec_loadbearing.py`)
+
+Verifisert mot faktisk lest test. Amendmenten er konstruert for å holde alle fem testene grønne:
+
+- **`test_method_spec_exists_with_required_structure` (test 1):** asserter at `_REQUIRED_MARKERS`
+  (`## 1.`–`## 12.` + `### Step 1..8` + `MUST`) FINNES. Markørene er presence-asserts, ikke
+  forbud mot ekstra seksjoner → ny `## 13.` og `### 2a` bryter ingenting. Render-bullet-endringen i
+  §3 Step 1 beholder `### Step 1 — ` intakt. **Grønn.**
+- **`test_method_spec_is_framework_neutral` (test 2):** grep-guard mot `_FRAMEWORK_NAMES` (MAF,
+  Claude, Azure, Foundry, OpenAI, Ollama, ...) over BEGGE spec-ene + persona-treet. All engelsk
+  spec-tekst i §1–§4 er bevisst framework-nøytral (ingen leverandørnavn; «a query-time retrieval
+  tool», ikke et produktnavn). **Grønn — forutsatt at innlimingen ikke introduserer et
+  leverandørnavn.** (Sjekk før commons-commit: `grep -nE '<_FRAMEWORK_NAMES>' method-spec.md
+  ingest-spec.md` → 0 treff.)
+- **`test_spec_documents_every_contract_field` (test 3):** completeness-drevet fra REELLE artefakter
+  + serializer — hvert felt koden konsumerer må stå som `` `felt` `` i spec-en. **I dag konsumerer
+  ingen kode D-F-feltene (D-F er ikke bygget)** → test 3 krever dem ikke ennå. Men §1.3s
+  cross-check-rader (`description`, `dimension`, `sources`, `provenance`, `id`, `label`,
+  `allowed_measure_types`, `allowed_code_prefixes`, de tre typene) sikrer at når koden lander
+  (dimensjonskatalog-loader, bibliotek-frontmatter-modell), er feltene ALLEREDE dokumentert → test 3
+  forblir grønn i byggeøkta. **Grønn nå; forhånds-dekket for byggetid.**
+- **`test_ingest_spec_exists_with_required_structure` (test 4):** asserter `_INGEST_REQUIRED_MARKERS`
+  (`## 1.`–`## 12.`) + verdict-reservasjonen (`` `type: verdict` `` + `promoted-verdict-`) +
+  `` `ingested_at` ``. Nye `### 4a`/`### 5a` bryter ingen markør; `library`-`okf_type` STYRKER
+  reservasjonen (MUST NOT be `verdict`). **Grønn.**
+- **`test_ingest_spec_documents_every_contract_field` (test 5):** drevet fra `ManifestV1` +
+  source-modellenes `model_fields`. **I dag finnes ingen `LibrarySource`-modell** → test 5 krever
+  ikke `library`-feltene ennå. §2s cross-check-rader (`root`, `dimension`, `okf_type`) forhånds-dekker
+  byggetid, akkurat som test 3. **Grønn nå; forhånds-dekket.**
+
+**Netto:** amendmenten er ren dokument-endring i commons; ingen av de fem integrity-testene i DETTE
+repoet blir røde av å hente den ned (pull), fordi ingen NY kode konsumerer feltene før byggeøkta —
+og da er feltene allerede dokumentert.
+
+### 5.2 D7-søsken-speiling (flagges, utenfor scope her)
+
+Amendmenten endrer de **delte** spec-ene begge stacker bygger fra. Per D-G pkt. 2 er OKF-formatlaget
+nå bevisst delt/speilet (endrer D7s «from spec alone» for formatlaget). Konsekvens: når method-spec
++ ingest-spec får denne innholdsmodellen, må **begge** implementasjoner re-implementere fra den nye
+spec-en — særlig Claude-SDK-søskenet, hvis `okf.py` (A2, revisjonspakka §0.2) i dag mangler skrive-
+halvdelen. **Dette utkastet leverer KUN spec-teksten; selve speilingen/byggingen er senere økt** (D-F
+innplassering: Fase 3-bolken; toolkit-repo blokkerer fabrikk-avhengige deler). Flagget her, ikke
+utført.
+
+### 5.3 Golden-suiten uberørt (begrunnet)
+
+- **`method-spec.md` §7 golden-suite** fryser VALIDATOR-utfallet (`validator` + `learning_surface`)
+  over IR-projeksjonen (`validator-input.json`). Innholdsmodellen legger til kontekst-lag-typer +
+  en summary-tier-render + dimensjonskatalog + `library`-ingest — **ingen** av dem rører
+  IR-projeksjonen, validator-semantikken eller `learning_surface`. `golden.json` +
+  `test_bygg_energi_mikro.py` er derfor uendret grønne.
+- **Render-endringen** påvirker `bundle_context`-output, men den er **ikke** golden-frosset (golden
+  fryser validator-tall, ikke read-context-strengen). De load-bearing invariantene som FINNES på
+  render (verdict-eksklusjon + empty-store-kontroll) bevares eksplisitt av amendmenten (§3.2:
+  bibliotek-tier er ikke-verdict, default byte-identisk). **Grønn.**
+- **`ingest-spec.md` §11 golden-extractions** er per-kildetype. `library` legger til en NY case
+  (`examples/ingest-golden-library/`); `file`/`sql`-goldens er uendret. **Grønn.**
+
+---
+
+## 6. Verifisering (utkastets egne kriterier)
+
+Testbare sjekker FØR commons-commit (etter operatør-godkjenning, i overførings-økta):
+
+1. **Framework-nøytralitet:** `grep -nE
+   '\bagent[_ -]framework\b|\bMAF\b|\bClaude\b|\bAnthropic\b|\bMicrosoft\b|\bAzure\b|\bFoundry\b|\bOpenAI\b|\bOllama\b|\bLangChain\b|\bAutoGen\b|\bSemantic Kernel\b|\bCrewAI\b|\bMagentic\b'`
+   over de amendede spec-ene → **0 treff** (samme regex som `_FRAMEWORK_NAMES`).
+2. **Struktur intakt:** `grep -n '### Step 1 — ' method-spec.md` → treff (render-bullet-endringen brøt
+   ikke Step-1-overskriften); `grep -n '## 13. The knowledge library' method-spec.md` → treff.
+3. **Verdict-reservasjon styrket:** ingest-spec `library`-`okf_type` MUST NOT be `verdict` er
+   verbatim i teksten (`grep -n 'MUST NOT be `verdict`' ingest-spec.md` → treff).
+4. **Cross-check-completeness forhånds-dekket:** hvert nytt felt (`sources`, `dimension`,
+   `provenance`, `allowed_measure_types`, `allowed_code_prefixes`, `root`) står som `` `felt` `` i
+   riktig spec (så integrity-test 3/5 blir grønn i byggeøkta).
+5. **Ingen kodeendring i denne økta:** `git status` i portfolio-optimiser viser kun den nye
+   `docs/plan/2026-07-14-commons-amendment-utkast.md`; `shared/` urørt; full suite fortsatt grønn.
+
+**Nøkkelantakelse (revisjonspakka §6), avgjort:** trinnvis-lesing **kan IKKE** spesifiseres uten å
+endre §3 Step 1s render-kontrakt (§3.1, forankret i method-spec.md:76–81 + ingest-spec.md:21–25 +
+okf.py:150-151). Den minimale, bakoverkompatible amendmenten er levert (§3.2) — merket som del av
+commons-amendmenten, slik pakka §6 krever ved NEI.