dynamisk-rettsstat/CLAUDE.md

dynamisk-rettsstat

This file is for development sessions in this repo. It is not loaded as plugin context, and claude plugin validate warns about a CLAUDE.md in the plugin root; that warning is expected.

Context

A Claude plugin (Claude Code and Cowork) that runs the model behind the concept note Den dynamiske rettsstaten on the user's own numbers: find the binding link in the criminal justice chain (diagnose), follow the measure over time (forlop), run scenarios (simuler) and change the model (forbedre). Users are Norwegian: people working in the justice chain (mostly non-programmers) and researchers. The note and its code live in ~/repos/den-dynamiske-rettsstaten (read-only from here). Open, non-commercial; nothing here is for sale.

Stack

• Skills only: skills/<name>/SKILL.md. No hooks, no MCP servers, no mod, no top-level bin/ (Cowork refuses a plugin with one).
• modell/kjor.py: the single entry point, Python 3.9+ standard library only. Finds a Python with numpy and scipy for the commands that need them; installs nothing unless miljo --opprett is run.
• modell/kjerne/: sim.py, diagnose.py, forlop.py, unmodified copies from the note's repo, pinned by sha256 in modell/kjerne/KILDE.json. numpy and scipy pinned in modell/requirements.txt (as the note).
• fasit/: reference output (22 data files and 5 printouts, 27 files) that kontroll compares against.
• modell/scenario.py (scenario runner over the core's five simulators), modell/kontroll.py (reproduction check), modell/arbeidskopi.py (copies the model to a folder the user owns), modell/utvidelser/ (mechanisms outside the core; each must reproduce the core exactly in a limit case).
• docs/: inndata.md, scenarioformat.md, modellkart.md, utvidelser.md, forbehold.md, Norwegian. The test for extensions reads the template in utvidelser.md between the markers <!-- mal:start --> and <!-- mal:slutt -->.
• eksempler/: eksempel_domstol.json (stylized), norge_2025.json (public Norwegian figures), scenarioer/ (six scenarios of our own, and notatet/ with 21 files that regenerate 20 of the note's 22 data files).

Conventions

• Never edit modell/kjerne/. It is synced from the note's repo, and these change together in one commit: the three files copied at the new commit; the commit and sha256 values in modell/kjerne/KILDE.json; fasit/ rebuilt with the note's own environment (its 22 data files must be byte-identical to the note's paper/data/ at that commit); and the constants NOTATETS_COMMIT, NOTATETS_KJERNE (3 sha256) and NOTATETS_FASIT (all 27 fasit/ files) in modell/kontroll.py. kontroll anchors on those constants, not on KILDE.json, so updating KILDE.json or fasit/ alone makes it report a change. Then run the full kontroll. A test fails if a core file does not match its sha256. No lint on the core. Changes to the model go in modell/utvidelser/ or in a user's working copy.
• User-facing text (skills, docs, script messages) is Norwegian bokmål, plain and direct, with the note's terms (ledd, skranke, restanse, utnyttelse, saksbehandlingstid, ledet utenom, den koordinerte regelen). Code, comments and this file may be English.
• Facts in docs and skills are read from the code or the note, never from memory. Where they differ, the code wins.
• The note's core sentence is quoted verbatim: «Innsatsen for å håndheve lover og regler bør løpende stå i forhold til hvor mye, og hvor alvorlig, de faktisk brytes.» Short form: «Straffebud og strafferammer ligger fast.»
• Skill frontmatter has only name and description (other keys make claude.ai reject an uploaded skill).
• ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_DATA} are substituted in skill text, but they are not environment variables in Bash. Skills write them literally into the command; kjor.py treats an empty --data or one containing ${ as not given and falls back to ~/.dynamisk-rettsstat. Both were substituted in Cowork too (operator's test 2026-11-11: the plugin under /root/.claude/plugins/synced/<id>/dynamisk-rettsstat, data under /root/.claude/plugins/data/dynamisk-rettsstat-synced). Cowork ran the commands in a Linux machine where numpy and scipy were already installed in the system Python, so the venv path is untested there.
• Skills never invent numbers, show the numbers as understood before computing, divide yearly figures by 12 and say so, relay script numbers verbatim, carry the caveats, and never install anything without asking. A rettsstat-modell/ in the user's folder is used only after asking, and only after kontroll --rask on it has been run and its level told to the user.
• Input to diagnose/forlop: kjor.py rejects unknown field names in a ledd or in styring (exit 2, with a suggestion); merknad, kilde, kilder are allowed there, and top-level fields are not checked.
• Scenarios: a changed base parameter stops the run unless the file sets startlikevekt (kalibrer or ubalanse); skills let the user choose and never pick. The models with a court queue drift slowly even without a shock (the note's own start is not an exact equilibrium); docs/forbehold.md has the numbers.
• Exit codes of kjor.py: 0 ok, 1 differences found by kontroll, 2 input or usage error (a core sys.exit("...") passes through as 2 with the message unchanged), 3 numpy/scipy missing.

Commands

• Development environment (versions pinned in pyproject.toml, group dev): python3 -m venv .venv && .venv/bin/pip install --group dev
• Tests: .venv/bin/pytest (about 2.5 minutes on the development machine, measured 2026-11-11); .venv/bin/pytest -m treg runs the note's full simulation (not timed).
• Lint and types (the core is excluded in pyproject.toml): .venv/bin/ruff check . and .venv/bin/mypy .
• Reproduction check against the note: .venv/bin/python modell/kjor.py kontroll (full run; about 1.5 minutes on the development machine, measured 2026-11-11) or .venv/bin/python modell/kjor.py kontroll --rask (skips the full run of sim.py). Six parts: core and fasit/ against the note's checksums, diagnose, forlop, full run, extensions' limit cases, scenario runner against fasit/data. --alt shows every differing line instead of the first 40 per comparison.
• Try the skills' commands: python3 modell/kjor.py diagnose eksempler/eksempel_domstol.json, python3 modell/kjor.py forlop eksempler/eksempel_domstol.json, python3 modell/kjor.py scenario eksempler/scenarioer/sjokkstorrelse_kjede.json --ut <scratch folder> (forlop and scenario need numpy and scipy; .venv/bin/python has them)
• Validate the plugin: claude plugin validate .
• Load the plugin locally: claude --plugin-dir .

Workflow

• Remote is Forgejo (git.fromaitochitta.com), never GitHub. Visibility, catalog entry and the move to open/ are the operator's decisions.
• PLAN.md and STATE.md are local working files (gitignored).
• Conventional Commits. Do not commit working documents.