substratum-cli 0.1.0

Substratum: verified-or-refused code, with provenance. The terminal over the comprehension engine.

Substratum

Verified-or-refused code, with provenance. Substratum is a deterministic comprehension engine for code. It never streams tokens and hopes — it produces a change only when that change passes a gate, and otherwise returns an honest, actionable refusal. Every result carries a run id you can replay byte-for-byte.

pip install substratum-cli

Then, in any repository:

substratum                      # open the interactive session (warms, then drives)

What it does

• summarize — describe the codebase in plain English, grounded in its real symbols (not a guess).
• failing — run the suite and list the failing tests; each becomes a ready fix target.
• verify — gate a diff (stdin, --staged, --commit): PASS / FAIL / per-hunk. The wedge — point it at any tool's diff and it tells you, deterministically, whether the change is real.
• fix — produce a verified fix for a failing test, or a named refusal.
• write — greenfield code from plain intent (derive-or-refuse; no test required).
• runs / show / replay / undo / apply / commit — a proof-carrying memory of every run.

summarize, failing, and verify run entirely on your machine — no account, no network, no code leaves your repo. They work air-gapped.

The hosted engine (optional)

fix and write draw on a large mined library. During the demo that library is hosted:

substratum login                # GitHub device flow; connects to the hosted engine

When logged in, write sends only your intent + signature, and fix receives a candidate that your machine then gates locally — so your code and your tests never leave your machine. substratum logout returns to fully-local operation.

The law

Never render unproven code. A refusal is a deliverable, not an error. Determinism is a button you press to catch us: run the same request twice and get the same run id, or replay any run and get a byte-identical result.

Coverage grows with data. Today the engine refuses more than it resolves, by design — the surface is built to feel complete at thin coverage, and the same commands silently resolve more as the library scales, with zero change on your end.