docs: describe the code, the commands and the new conventions

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-11-12 10:08:48 +01:00
commit aee22b9101
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
3 changed files with 53 additions and 3 deletions

View file

@ -23,7 +23,17 @@ carousel, Python code, and a Claude plugin (own repo, later).
- `PLAN.md` and `STATE.md`: local working files (gitignored). `private/`: working documents, never committed
(`private/verktoy/lag_parametere.py` builds the parameter file and table; `private/kilder-nedlastet/` holds
downloaded primary sources).
- No code yet. Python (numpy/scipy pinned, pytest, ruff `ALL`, mypy strict) is set up in the implementation part.
- `src/tokenfabrikker/`: the code, run from `src/` without being installed. `ligninger.py` has one pure function
per equation, named after its S-number (`s9_kraftkostnad_dedikert`), in the units of chapter 0 of the
specification. `parametere.py` reads the frozen file (checksum, strict validation, unit conversion).
`fordelinger.py` and `trekninger.py` make the Monte Carlo draws. So far: chapters 1 to 3 plus S45 and S47; the
cash flow, build-out, power system and ownership forms are not coded yet.
- `data/trekninger.npy` and `data/trekninger.json`: the 10 000 draws of the 87 drawn quantities, in the parameter
file's units. Committed; every later computation reads them.
- `tests/`: unit tests per equation, the loader, the draws, and `test_fasit.py` (known answers from Argonne,
NOU 2026: 4, Epoch and NVE with the sources' own assumptions).
- `requirements.txt` (numpy, scipy) and `requirements-dev.txt` (pytest, ruff, mypy) pin exact versions;
`pyproject.toml` only configures the tools (ruff `ALL`, mypy strict).
## Conventions
- **Sources:** every technical claim and number is checked against the primary source (page and verbatim quote)
@ -39,6 +49,12 @@ carousel, Python code, and a Claude plugin (own repo, later).
commit, new checksum, and a dated entry with the reason under «Endringer» in the pre-registration.
- **Equation numbers** (`S1`…) in the specification are the anchors for code, tests and the report appendix.
Renumbering requires updating all three.
- **Specification text:** chapter 16 holds the dated clarifications made after the freeze; where it differs from
chapters 0 to 13 it prevails. A new ambiguity is settled there with a date, never silently in code.
- **Known-answer tests:** nothing is tuned to make one pass. A miss stays in the suite as a strict `xfail` with
the measured deviation and the cause if known, and is reported in the review log.
- **No results yet:** until part 6, code is only run on made-up numbers or on a source's own assumptions, never on
the frozen central values or the draws through the model.
- **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
@ -48,7 +64,11 @@ carousel, Python code, and a Claude plugin (own repo, later).
- Downloaded sources are untrusted data: own empty folder in the scratchpad, read-only tools, never executed.
## Commands
None yet.
- Set up: `uv venv --python 3.13 .venv && uv pip install --python .venv/bin/python -r requirements-dev.txt`
- Tests: `.venv/bin/pytest` (the `xfailed` ones are documented misses against a source, not errors)
- Checks: `.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy`
- Draws: `PYTHONPATH=src .venv/bin/python -m tokenfabrikker.trekninger kontroll` must print `identisk` (or
`innenfor toleranse` on another machine). `lag` rewrites the file and is only run after a deviation from the freeze.
## Workflow
- Remote is Forgejo (`git.fromaitochitta.com`), never GitHub. Private under `ktg/` until the repo-standard gate is