docs(modell): add model specification draft 2 and review log

Draft 1 was read by two independent reviewers (a subject reviewer and a
devil's advocate). Draft 2 corrects the equations they found wrong
(levelised price, token cost unit, welfare sign, double counting) and
models off-grid operation with unit size limits and reserve units.
Findings that touch the pre-registered criteria are listed as open
decisions, not applied.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-11-11 22:20:04 +01:00
commit 5a4d9b0072
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
5 changed files with 692 additions and 2 deletions

View file

@ -15,6 +15,8 @@ carousel, Python code, and a Claude plugin (own repo, later).
## Stack
- `kilder/`: the source bank, one Markdown file per area. Every model parameter must trace to an entry here.
- `FORHANDSREGISTRERING.md`: the approved direction and pre-registered criteria (M1–M7). Committed.
- `modell/spesifikasjon.md`: the model specification (equations S1–S32, parameter candidates with source-bank
references). `modell/fagfellevurdering-utkast-1.md`: review findings on draft 1 and what was done.
- `PLAN.md` and `STATE.md`: local working files (gitignored). `private/`: working documents, never committed.
- No code yet. Python (numpy/scipy pinned, pytest, ruff `ALL`, mypy strict) is set up in the implementation part.
@ -25,8 +27,11 @@ carousel, Python code, and a Claude plugin (own repo, later).
not facts: check the load-bearing ones yourself before they are used.
- **Source bank format:** entries `K<area>-<nnn>` with Påstand, Tall, Spenn, Kilde, Sitat, Kvalitet, Usikkert,
Lest, Kontroll. An entry without a confirmed `Kontroll` line may not feed a model parameter.
- **Pre-registration:** the criteria in `FORHANDSREGISTRERING.md` are fixed before anything is computed. Changing them after
results exist requires a dated entry with the reason under «Endringer» in that file.
- **Pre-registration:** the criteria in `FORHANDSREGISTRERING.md` are approved by the operator and fixed before
anything is computed. Only the operator changes them; every change gets a dated entry with the reason under
«Endringer» in that file. Parameters are frozen in their own commit before the first result run.
- **Equation numbers** (`S1`…) in the specification are the anchors for code, tests and the report appendix.
Renumbering requires updating all three.
- **Neutrality:** vendors and companies are data sources, cited neutrally, never recommended. Nothing here
advertises a business. "Business case" means profitability for Norway, not something for sale.
- **Sadhguru** is mentioned in exactly one sentence, as inspiration, in the report's foreword and in README; never