Metadata-Version: 2.3
Name: spotregen
Version: 0.1.1
Summary: Regenerative Software tooling: check intent, evaluations and provenance of regenerable units, and drive blind regeneration
Author: bartzbeielstein
Author-email: bartzbeielstein <32470350+bartzbeielstein@users.noreply.github.com>
License: AGPL-3.0-or-later
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.13
Project-URL: Documentation, https://advm1.gm.fh-koeln.de/~bartz/spotregen/
Project-URL: Repository, https://git-ce.rwth-aachen.de/thomas.bartz-beielstein/spotregen
Project-URL: Issues, https://git-ce.rwth-aachen.de/thomas.bartz-beielstein/spotregen/-/issues
Description-Content-Type: text/markdown

# 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 gate (`spotregen check`) for `make guard`, plus reports
  (`status`, `deletion-test`, `context`, `compact`, `new-unit`) and two
  non-deterministic drivers (`blind`, `local`) that regenerate a unit with an LLM.

## Install

```bash
uv add --dev spotregen
```

## Use

```bash
spotregen check [--strict]            # the gate: 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 new-unit MODULE --pace P --risk R [--dry-run]
spotregen blind 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.

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

```bash
make sync && make test-fast     # environment and fast tests
make verify                     # guard + lint + test + doc, the gate before a push
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [RELEASING.md](RELEASING.md). The design
is recorded in [ADR 0001](docs/adr/0001-spotregen-package.md).

## License

AGPL-3.0-or-later.
