spotregen

Tooling for Regenerative Software in the sense of Chad Fowler: code is disposable, the knowledge around it is the asset. A module is safely replaceable when it can be deleted and rebuilt from knowledge that lives outside its implementation. spotregen reads that knowledge from a tracked regen/ tree and checks it against the source tree.

• Standard library only: zero runtime dependencies, Python 3.13 or later.
• It never imports the modules it describes; it reads the source with ast.
• A deterministic static check (spotregen check) for make guard, plus reports (status, deletion-test, context, compact, new-unit), three measures (measures for intent coverage and specification size, mutate for the mutation score of one unit, measures --mutation-score for all three of every unit) and two non-deterministic drivers (claude, local) that regenerate a unit with an LLM.

Install

uv add --dev spotregen

Use

spotregen check [--strict]            # the static check: exit 1 on errors
spotregen status                      # units by pace and coverage
spotregen deletion-test UNIT          # blast radius and knowledge gaps
spotregen context UNIT [-o FILE]      # regeneration bundle, no bodies
spotregen compact                     # compaction candidates
spotregen measures [--mutation-score]  # intent coverage and specification size;
                                      # --mutation-score adds the score (slow: runs every mutant)
spotregen mutate UNIT [--out FILE]    # mutation score: planted mutants
spotregen new-unit MODULE --pace P --risk R [--dry-run]
spotregen gui                         # the graphical interface (tkinter, see below)
spotregen claude UNIT [...]           # regenerate with `claude -p` (needs claude)
spotregen local UNIT --model M [...]  # regenerate with a local LM Studio model

--root DIR selects the repository (default: search upwards for regen/architecture.toml); python -m spotregen works as well. A repository carries:

• regen/architecture.toml: the compilation target (allowed imports, accepted cycles, pace policy, conventions, scan directories).
• regen/units/<unit>.toml: one regenerable unit with intent, evaluations and consumers.
• regen/decisions/<id>.toml: provenance records.

Graphical interface

spotregen gui (also spotregen-gui and python -m spotregen.gui) opens a window with an Overview and a view for each command except the drivers: Check, Status, Context, Deletion test, Compact, Measures and New unit, plus Runs, Mutate and Local for the long-running jobs. It uses tkinter from the standard library, so it adds no dependency, and it shows the exact command line under every action. A Python without tkinter gets a message with the fix; Python builds managed by uv include it. QUICKSTART.md walks through one example on the sample repository. See docs/gui.qmd and ADR 0002.

The schema, the finding codes and the tutorials are in the documentation, https://advm1.gm.fh-koeln.de/~bartz/spotregen/. A minimal repository for trying it out is built by spotregen.make_sample_repo.

Develop

make sync && make test-fast     # environment and fast tests
make verify                     # guard + lint + test + doc, the pre-release verification

See CONTRIBUTING.md and RELEASING.md. The design is recorded in ADR 0001 and, for the graphical interface, ADR 0002.

License

AGPL-3.0-or-later.