Regeneration drivers
spotregen claude and spotregen local regenerate one unit with an LLM and score the result. The cells on this page are not executed: they need Claude Code or a local model server, they are not deterministic and they write to your repository’s git metadata.
make guard
An LLM call is not deterministic. The drivers are for experiments and for measuring how good a specification is. The static check is spotregen check.
The protocol
A protocol is the written, repeatable procedure of a run. Each driver follows one, and run.toml names it in the field protocol (see run records).
Definition 1 (Regeneration) The generator receives the regeneration bundle (see the bundle) and the files named by --allow, never the module it must write. The module is then copied into a detached git worktree of HEAD in which the original was deleted, and judged by the unit’s evaluations and, once, by its unit tests and its dependents inside the repository: every declared consumer of kind code below the source directory is imported, and every live docstring example of the unit’s public names, taken from the original in HEAD, is run against the new module. Failing evaluations are handed back for up to --attempts tries.
Both commands take the usual --root and resolve the unit like every other command (a dotted name or a unique suffix); a malformed unrelated unit record aborts with exit 2.
spotregen claude core.calc --allow src/mypkg/core/helpers.py --out /tmp/claude-calc
spotregen local core.calc --model my-model --allow src/mypkg/core/helpers.py --out /tmp/local-calc--allow FILE is resolved against the repository root; a path outside it is refused. --out DIR is the run directory (default: a temporary one). --python PATH selects the interpreter that scores candidates (default: <root>/.venv/bin/python if present, otherwise the interpreter running spotregen); the scoring environment holds only PYTHONPATH=<source_dir> from the architecture and a fixed PATH.
spotregen claude: Claude Code in restricted mode
The generator is claude -p in --restricted and --safe-mode with the tools Read, Write and Edit and the workspace as its only directory. It has no shell, so it can neither read the deleted module nor run the tests: blindness is enforced, not requested. The run is blind, and confinement makes the generator memoryless. The command needs claude and git on PATH and exits 2 with a clear message when one is missing.
spotregen claude core.calc --dry-run # prepare the workspace, print the command
spotregen claude core.calc --score candidate.py # score an existing module, no LLM
spotregen claude core.calc --model claude-opus-5-5 --attempts 3
spotregen claude core.calc --base-url http://localhost:1234 --model my-model # a local model through Claude Code--dry-run and --score do not need claude.
spotregen local: short sessions against a local server
Without Claude Code and without one long agent session, a deterministic driver sends fresh, short sessions (generate, repair, gap report) to the OpenAI-compatible /v1/completions endpoint of a local server such as LM Studio, with standard-library HTTP. The model is offered no tools; it sees only what the driver puts into the prompt.
spotregen local core.calc --model my-model --template chatml --reasoning off
spotregen local core.calc --model devstral --template mistral --reasoning none
spotregen local core.calc --model my-model --canary # send the confinement prompt and stop| option | meaning |
|---|---|
--endpoint URL |
server, default http://127.0.0.1:1234; only localhost is accepted, anything else is refused |
--template |
chatml (Qwen) or mistral (Devstral; needs --reasoning none) |
--reasoning |
off prefills an empty think block, on leaves it to the model, none for models without a reasoning mode |
--repair-seed |
fixed: every session uses --seed; step: the repair of attempt n uses --seed + n |
--attempts, --max-tokens, --report-tokens, --session-timeout, --failure-chars |
budgets |
--temperature, --top-p, --top-k, --seed |
sampling |
The command refuses to run without lsof: during the run it samples the remote endpoints of its own sockets and records them, which is the evidence that no code or prompt left the machine. Before the first session it asks the server for GET /v1/models and stops with a clear error if the server is not there.
What a run leaves behind
| file | content |
|---|---|
run.toml |
unit, protocol, spotregen_version, start and finish, base commit (marked dirty if the working tree had changes), generator (model, harness, flags), input hashes (bundle_sha256), one [[attempt]] per try with evaluation, unit-test and dependent scores; local adds [[session]] (tokens, seconds, finish reason) and [egress] |
bundle.md |
the bundle the generator was given |
<module>-<n>.py, evaluations-<n>.txt, unit_tests.txt, dependents.txt |
each candidate and its scores; dependents.txt has one PASS/FAIL line per dependent |
transcript-<n>.jsonl, report-<n>.md |
claude: the stream-json transcript and the generator’s report |
sessions.jsonl, report.md |
local: every prompt and reply, and the gap report |
The generator’s report, a list of every place where the bundle was ambiguous, silent or contradictory, is the most valuable output: fix the spec where it points.
Exit codes
0 if the last attempt’s evaluations and the dependents pass, 1 otherwise; 2 for a spec, unit, option or missing-tool error (no claude, git or lsof, a non-local endpoint, an --allow file outside the repository).