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

# 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, licences, ...). 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.