lean-lockstep 0.1.0__tar.gz

lean_lockstep-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes are listed here. Versions follow [semantic versioning](https://semver.org);
+before 1.0, a minor version may break compatibility.
+
+## 0.1.0 (2026-10-18)
+
+First public release. Extracted from the harness of two Lean research projects and generalized.
+
+- State derived from the compiled environment: `lockstep extract` reports every blueprint node as
+  open, claimed or closed; `status`, `ready`, `node show`, `search`.
+- Locked statements: `harness/statements.lock`, `node add`, `node restate`, `node retire`,
+  `lock refresh`, and `python -m lockstep.lock` for CI.
+- Coordination: claims with intent and outcome, `log`, `journal`, `note`.
+- Memory-guarded builds and jobs: `build`, `check`, `job run`, `job wait`, `worker`, under a shared
+  budget.
+- Integrity: a cached per-module axiom audit, import-layer checks, `rules` (agent rule files in
+  step), and `hook pre-commit` for git.
+- Client integration: an MCP server (`lockstep-mcp`) exposing every command; Claude Code hooks
+  (`hook session-start`, `hook pre-bash`).
+- Experimental: durable operations, proof capture/check/prove, `node finish`, finite probes,
+  `context`, the research-library catalog, certificate layers and `storage share`.

lean_lockstep-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Gavin Litchfield
+Copyright (c) 2026 Matt Pocock (Wayfinder-derived portions)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lean_lockstep-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+# The sdist carries what the tests and the docs refer to.
+include CHANGELOG.md
+graft docs
+graft examples
+graft bin
+graft systemd
+graft tests
+prune examples/*/.lake
+prune examples/*/.lockstep
+global-exclude __pycache__ *.py[cod]

lean_lockstep-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: lean-lockstep
+Version: 0.1.0
+Summary: Coordinate several agents on a Lean 4 formalization: state derived from the compiled environment, locked statements, recorded claims and memory-guarded jobs
+Author: Gavin Litchfield
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GLitchfield/lean-lockstep
+Project-URL: Repository, https://github.com/GLitchfield/lean-lockstep
+Project-URL: Issues, https://github.com/GLitchfield/lean-lockstep/issues
+Project-URL: Changelog, https://github.com/GLitchfield/lean-lockstep/blob/main/CHANGELOG.md
+Keywords: lean4,formalization,theorem-proving,blueprint,ai-agents,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == "mcp"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: research
+Requires-Dist: numpy; extra == "research"
+Dynamic: license-file
+
+# lean-lockstep
+
+A project harness for Lean 4 formalization work done by several agents at once: AI coding agents
+of any kind (anything that can run a shell command or call an MCP tool) and people. It keeps the
+state of the project (which statements are open, claimed, proved, and what depends on what)
+derived from the compiled Lean environment, and it records who is doing what, why, and with how
+much memory.
+
+- **State comes from Lean, not from a document.** Each open statement is a *node*: a theorem
+  with a `sorry` in its own blueprint module, tagged in its docstring. `lockstep extract` reads the
+  compiled environment and reports each node as open, claimed or closed (sorry-free with
+  allowlisted axioms). There is no hand-kept status file that can drift.
+- **Approved statements are locked.** `harness/statements.lock` records the type hash of every
+  approved statement. A proof that quietly weakens its statement shows up as a lock violation;
+  changing a statement takes `lockstep node restate`, which logs who approved it and why. This is the
+  failure mode that matters most when agents write the proofs.
+- **Agents coordinate through the harness.** Claims expire and carry the intent (`--why`); every
+  release records an outcome; `lockstep log` and `lockstep journal` keep the trail; long commands run as
+  recorded, memory-capped jobs that every agent can see.
+- **Audits scale.** The axiom audit is a per-module taint scan with a cache, which finishes on
+  projects where `#print axioms` does not.
+- **No client or model is assumed.** Every command has a CLI and an MCP tool. A git pre-commit
+  hook guards commits for everyone; optional Claude Code hooks add a session banner and a guard
+  against compute launched outside the harness.
+
+Status: experimental (0.1). Built and used in two research projects; expect rough edges outside
+them. Linux first.
+
+## Requirements
+
+- Python 3.11 or newer. The core has no dependencies; extras: `mcp` (MCP server), `test`
+  (pytest), `research` (NumPy for research-library probes).
+- Lean 4 through [elan](https://github.com/leanprover/elan), Lake, and git.
+- The memory guard runs each `lake` invocation in a capped `systemd-run --user` scope, so it
+  needs Linux with a systemd user session. Elsewhere set `[build] guard = false`.
+- `bwrap` (bubblewrap) for the sandboxed proof checks of the experimental automation layer.
+
+## Try it
+
+`examples/minimal` is a Lean-only Lake project (no Mathlib) with one core lemma and an empty
+blueprint. From a checkout of this repository:
+
+```console
+cd examples/minimal
+export LOCKSTEP_AGENT=me:demo            # every claim, job and log entry is recorded under this id
+../../bin/lockstep build core
+../../bin/lockstep extract               # writes harness/nodes.json, index.json, status.md
+../../bin/lockstep node add --name double_succ --ws A --kind formalization \
+  --type "(n : Nat) : (n + 1) + (n + 1) = 2 * n + 2" \
+  --description "Doubling a successor." --depends double --dangling-ok "example"
+../../bin/lockstep ready                 # Demo.double_succ is open and ready
+../../bin/lockstep claim double_succ --why "rewrite with Demo.double, then omega"
+# replace the `sorry` in DemoBlueprint/A/DoubleSucc.lean with `rw [double]; omega`
+../../bin/lockstep check double_succ     # sorry=False status=closed
+../../bin/lockstep close double_succ     # moves it into the core library, records the attempt
+../../bin/lockstep audit && ../../bin/lockstep journal
+```
+
+`tests/test_example_lifecycle.py` runs the same sequence whenever `lake` is installed. To start
+over, run `git checkout -- . && git clean -fdx .` in `examples/minimal`.
+
+## Installing
+
+The harness writes Lean files into the project (the extractor, node modules) and its lock hashes
+depend on the toolchain, so pin the version a project uses. Either:
+
+- **From PyPI**, which puts `lockstep` and `lockstep-mcp` on the `PATH`:
+  ```console
+  uv tool install "lean-lockstep[mcp]==0.1.0"     # or: pipx install "lean-lockstep[mcp]==0.1.0"
+  ```
+  Without PyPI access, install a tag from git instead:
+  `uv tool install "lean-lockstep[mcp] @ git+https://github.com/GLitchfield/lean-lockstep@v0.1.0"`.
+- **As a git submodule**, pinned by commit and upgraded by bumping the pin, which suits a project
+  that also develops the harness:
+  ```console
+  git submodule add https://github.com/GLitchfield/lean-lockstep tools/lockstep
+  uv venv tools/lockstep/.venv && uv pip install -e "tools/lockstep[mcp]"
+  ```
+  `tools/lockstep/bin/lockstep` and `tools/lockstep/bin/lockstep-mcp` prefer that virtualenv and
+  fall back to the system `python3`.
+
+The commands below write `lockstep`; with a submodule, that is `tools/lockstep/bin/lockstep`.
+
+## Adopting it in a project
+
+1. Give the Lake package two libraries: a core library (proved results only) and a blueprint
+   library whose root file imports every node module. `lockstep node add` maintains that root.
+2. Copy `examples/minimal/harness/` and edit `harness/config.toml`: namespaces, layers, build
+   targets, memory caps. Start `statements.lock` as `{}` and `allowlist.json` as `[]`.
+3. Ignore the harness state directory (`.lockstep/` with `[project] state_home = ".lockstep"`).
+4. Write the agent rules into the files your clients read (`AGENTS.md`, `CLAUDE.md`, ...) and
+   list them under `[rules]`; `lockstep rules` checks that they carry the same rule list (cheap enough
+   for CI). `examples/minimal/AGENTS.md` is a starting point. Tell each agent to export a stable
+   `LOCKSTEP_AGENT` (for example `<client>:<session id>`); claims and logs are recorded under it.
+5. Guard commits with the git hook, which works whoever commits:
+   ```console
+   printf '#!/bin/sh\nexec lockstep hook pre-commit\n' > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+   ```
+   It refuses a commit that fails `lockstep layers`, `lockstep extract --check` (generated files out of date
+   or a locked statement changed) or `lockstep audit --changed`.
+6. Register the MCP server with your client: command `lockstep-mcp` (or `tools/lockstep/bin/lockstep-mcp`), stdio,
+   no arguments. For example `.mcp.json`:
+   ```json
+   { "mcpServers": { "lockstep": { "command": "tools/lockstep/bin/lockstep-mcp", "args": [] } } }
+   ```
+7. Optionally, for Claude Code, add the session and shell hooks to `.claude/settings.json`:
+   ```json
+   { "hooks": {
+       "SessionStart": [{ "hooks": [{ "type": "command", "command": "tools/lockstep/bin/lockstep hook session-start" }] }],
+       "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "tools/lockstep/bin/lockstep hook pre-bash" }] }] } }
+   ```
+   `session-start` prints the session's agent id and `lockstep status --brief`. `pre-bash` blocks a
+   bare `nohup`/`systemd-run` (compute goes through `lockstep job run`) and runs the commit guard
+   before `git commit`/`git push`. Any client whose hooks pass the same JSON on stdin can use them.
+8. In CI, `python3 -m lockstep.lock BASE_LOCK HEAD_LOCK` (with `PYTHONPATH=tools/lockstep` for a submodule)
+   prints the log files a lock change must touch: `restatements.md` when an approved statement
+   changed or disappeared, `retired.md` for a refutation. New entries need none.
+9. Optionally, `tools/lockstep/systemd/install.sh` (from a checkout) installs a `lockstep-nightly-<project
+   id>` user timer (03:00) that runs the guarded core build, `lockstep extract --check` and `lockstep audit`.
+
+## Commands
+
+| Area | Commands |
+|---|---|
+| State | `status`, `ready`, `node show`, `search`, `extract`, `extract --check`, `doctor` |
+| Statements | `node add`, `node restate`, `node retire`, `lock refresh` (after a toolchain bump) |
+| Work | `claim`, `release`, `check`, `close`, `falsify` (conjecture nodes) |
+| Builds and jobs | `build core` / `blueprint` / `node`, `job run`, `job wait`, `job list`, `worker` |
+| Trail | `log`, `journal`, `note` (weekly summary) |
+| Integrity | `audit`, `layers`, `rules`, `hook pre-commit` |
+| Client hooks | `hook session-start`, `hook pre-bash` |
+
+Every command takes `--json`, and all but the hooks are also MCP tools. Node names may be
+dotted relative to the declaration namespace (`--name List.foo` declares `theorem List.foo` in
+it), and `--depends` lists the project declarations a node waits on (library lemmas belong in
+the description).
+
+### Experimental
+
+These work in the projects they came from but are less general; see
+[`docs/automation.md`](docs/automation.md):
+
+- **Automation layer**: durable `operation …` workflows run by `lockstep worker`, a results `inbox`,
+  `proof capture|check|prove`, `node finish`, `probe run|replay`, `context`.
+- **Research library**: `lib search|show|list` over a project catalog
+  (`harness/research/catalog.json`).
+- **Certificate layers**: `[layers]` rules for generated proof-module families, and
+  `storage share` for their compiled artifacts.
+
+## Things that cost hours to learn
+
+- **Never `import` the project modules at the top of a `lake env lean --run` script that also
+  calls `importModules` on them.** The script's own import maps the oleans; the second load
+  cannot mmap at the same addresses and reads them into anonymous memory instead (37 GB and a
+  cgroup OOM kill on a project with large certificate modules). The extractor template imports
+  only `Lean`; `main` imports the project.
+- **Never use `importAll := true`** for the extractor environment (30+ GB). A plain import
+  exposes every theorem value in `env.header.moduleData`.
+- **Never run bare `lake build` on big targets.** Lake 5 has no `-j`; two dozen parallel
+  compilers exhaust a 20 GB guard. `lockstep build` builds Lake's out-of-date list one module per
+  guarded invocation first.
+- **`#print axioms` does not finish on large generated proof families** (16 TB read in 3.5 h);
+  the extractor's module-order taint scan with a per-module cache is the audit path.
+- **A module-system core root (`module` header) cannot import plain files.** When the core root
+  uses it, nodes are written in module form from the start, so a proof elaborates against the
+  same imports before and after `lockstep close`.
+- **The elaborator moves parts of a proof into auxiliary declarations** (`foo._proof_1`), so a
+  dependency scan of a theorem's value alone reports the auxiliaries instead of the lemmas they
+  use. The extractor looks through a declaration's own auxiliaries.
+
+## Development
+
+```console
+uv venv .venv && uv pip install -e ".[test,mcp,research]"
+.venv/bin/python -m pytest
+```
+
+Releases follow semantic versioning (0.x: minor versions may break). Changes are listed in
+[`CHANGELOG.md`](CHANGELOG.md). To release, bump `__version__` in `lockstep/__init__.py`, add the
+changelog entry, and push a `vX.Y.Z` tag: `.github/workflows/release.yml` builds the sdist and
+wheel and publishes them to PyPI through trusted publishing.
+
+## License
+
+MIT; see [`LICENSE`](LICENSE).

lean_lockstep-0.1.0/README.md

@@ -0,0 +1,185 @@
+# lean-lockstep
+
+A project harness for Lean 4 formalization work done by several agents at once: AI coding agents
+of any kind (anything that can run a shell command or call an MCP tool) and people. It keeps the
+state of the project (which statements are open, claimed, proved, and what depends on what)
+derived from the compiled Lean environment, and it records who is doing what, why, and with how
+much memory.
+
+- **State comes from Lean, not from a document.** Each open statement is a *node*: a theorem
+  with a `sorry` in its own blueprint module, tagged in its docstring. `lockstep extract` reads the
+  compiled environment and reports each node as open, claimed or closed (sorry-free with
+  allowlisted axioms). There is no hand-kept status file that can drift.
+- **Approved statements are locked.** `harness/statements.lock` records the type hash of every
+  approved statement. A proof that quietly weakens its statement shows up as a lock violation;
+  changing a statement takes `lockstep node restate`, which logs who approved it and why. This is the
+  failure mode that matters most when agents write the proofs.
+- **Agents coordinate through the harness.** Claims expire and carry the intent (`--why`); every
+  release records an outcome; `lockstep log` and `lockstep journal` keep the trail; long commands run as
+  recorded, memory-capped jobs that every agent can see.
+- **Audits scale.** The axiom audit is a per-module taint scan with a cache, which finishes on
+  projects where `#print axioms` does not.
+- **No client or model is assumed.** Every command has a CLI and an MCP tool. A git pre-commit
+  hook guards commits for everyone; optional Claude Code hooks add a session banner and a guard
+  against compute launched outside the harness.
+
+Status: experimental (0.1). Built and used in two research projects; expect rough edges outside
+them. Linux first.
+
+## Requirements
+
+- Python 3.11 or newer. The core has no dependencies; extras: `mcp` (MCP server), `test`
+  (pytest), `research` (NumPy for research-library probes).
+- Lean 4 through [elan](https://github.com/leanprover/elan), Lake, and git.
+- The memory guard runs each `lake` invocation in a capped `systemd-run --user` scope, so it
+  needs Linux with a systemd user session. Elsewhere set `[build] guard = false`.
+- `bwrap` (bubblewrap) for the sandboxed proof checks of the experimental automation layer.
+
+## Try it
+
+`examples/minimal` is a Lean-only Lake project (no Mathlib) with one core lemma and an empty
+blueprint. From a checkout of this repository:
+
+```console
+cd examples/minimal
+export LOCKSTEP_AGENT=me:demo            # every claim, job and log entry is recorded under this id
+../../bin/lockstep build core
+../../bin/lockstep extract               # writes harness/nodes.json, index.json, status.md
+../../bin/lockstep node add --name double_succ --ws A --kind formalization \
+  --type "(n : Nat) : (n + 1) + (n + 1) = 2 * n + 2" \
+  --description "Doubling a successor." --depends double --dangling-ok "example"
+../../bin/lockstep ready                 # Demo.double_succ is open and ready
+../../bin/lockstep claim double_succ --why "rewrite with Demo.double, then omega"
+# replace the `sorry` in DemoBlueprint/A/DoubleSucc.lean with `rw [double]; omega`
+../../bin/lockstep check double_succ     # sorry=False status=closed
+../../bin/lockstep close double_succ     # moves it into the core library, records the attempt
+../../bin/lockstep audit && ../../bin/lockstep journal
+```
+
+`tests/test_example_lifecycle.py` runs the same sequence whenever `lake` is installed. To start
+over, run `git checkout -- . && git clean -fdx .` in `examples/minimal`.
+
+## Installing
+
+The harness writes Lean files into the project (the extractor, node modules) and its lock hashes
+depend on the toolchain, so pin the version a project uses. Either:
+
+- **From PyPI**, which puts `lockstep` and `lockstep-mcp` on the `PATH`:
+  ```console
+  uv tool install "lean-lockstep[mcp]==0.1.0"     # or: pipx install "lean-lockstep[mcp]==0.1.0"
+  ```
+  Without PyPI access, install a tag from git instead:
+  `uv tool install "lean-lockstep[mcp] @ git+https://github.com/GLitchfield/lean-lockstep@v0.1.0"`.
+- **As a git submodule**, pinned by commit and upgraded by bumping the pin, which suits a project
+  that also develops the harness:
+  ```console
+  git submodule add https://github.com/GLitchfield/lean-lockstep tools/lockstep
+  uv venv tools/lockstep/.venv && uv pip install -e "tools/lockstep[mcp]"
+  ```
+  `tools/lockstep/bin/lockstep` and `tools/lockstep/bin/lockstep-mcp` prefer that virtualenv and
+  fall back to the system `python3`.
+
+The commands below write `lockstep`; with a submodule, that is `tools/lockstep/bin/lockstep`.
+
+## Adopting it in a project
+
+1. Give the Lake package two libraries: a core library (proved results only) and a blueprint
+   library whose root file imports every node module. `lockstep node add` maintains that root.
+2. Copy `examples/minimal/harness/` and edit `harness/config.toml`: namespaces, layers, build
+   targets, memory caps. Start `statements.lock` as `{}` and `allowlist.json` as `[]`.
+3. Ignore the harness state directory (`.lockstep/` with `[project] state_home = ".lockstep"`).
+4. Write the agent rules into the files your clients read (`AGENTS.md`, `CLAUDE.md`, ...) and
+   list them under `[rules]`; `lockstep rules` checks that they carry the same rule list (cheap enough
+   for CI). `examples/minimal/AGENTS.md` is a starting point. Tell each agent to export a stable
+   `LOCKSTEP_AGENT` (for example `<client>:<session id>`); claims and logs are recorded under it.
+5. Guard commits with the git hook, which works whoever commits:
+   ```console
+   printf '#!/bin/sh\nexec lockstep hook pre-commit\n' > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+   ```
+   It refuses a commit that fails `lockstep layers`, `lockstep extract --check` (generated files out of date
+   or a locked statement changed) or `lockstep audit --changed`.
+6. Register the MCP server with your client: command `lockstep-mcp` (or `tools/lockstep/bin/lockstep-mcp`), stdio,
+   no arguments. For example `.mcp.json`:
+   ```json
+   { "mcpServers": { "lockstep": { "command": "tools/lockstep/bin/lockstep-mcp", "args": [] } } }
+   ```
+7. Optionally, for Claude Code, add the session and shell hooks to `.claude/settings.json`:
+   ```json
+   { "hooks": {
+       "SessionStart": [{ "hooks": [{ "type": "command", "command": "tools/lockstep/bin/lockstep hook session-start" }] }],
+       "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "tools/lockstep/bin/lockstep hook pre-bash" }] }] } }
+   ```
+   `session-start` prints the session's agent id and `lockstep status --brief`. `pre-bash` blocks a
+   bare `nohup`/`systemd-run` (compute goes through `lockstep job run`) and runs the commit guard
+   before `git commit`/`git push`. Any client whose hooks pass the same JSON on stdin can use them.
+8. In CI, `python3 -m lockstep.lock BASE_LOCK HEAD_LOCK` (with `PYTHONPATH=tools/lockstep` for a submodule)
+   prints the log files a lock change must touch: `restatements.md` when an approved statement
+   changed or disappeared, `retired.md` for a refutation. New entries need none.
+9. Optionally, `tools/lockstep/systemd/install.sh` (from a checkout) installs a `lockstep-nightly-<project
+   id>` user timer (03:00) that runs the guarded core build, `lockstep extract --check` and `lockstep audit`.
+
+## Commands
+
+| Area | Commands |
+|---|---|
+| State | `status`, `ready`, `node show`, `search`, `extract`, `extract --check`, `doctor` |
+| Statements | `node add`, `node restate`, `node retire`, `lock refresh` (after a toolchain bump) |
+| Work | `claim`, `release`, `check`, `close`, `falsify` (conjecture nodes) |
+| Builds and jobs | `build core` / `blueprint` / `node`, `job run`, `job wait`, `job list`, `worker` |
+| Trail | `log`, `journal`, `note` (weekly summary) |
+| Integrity | `audit`, `layers`, `rules`, `hook pre-commit` |
+| Client hooks | `hook session-start`, `hook pre-bash` |
+
+Every command takes `--json`, and all but the hooks are also MCP tools. Node names may be
+dotted relative to the declaration namespace (`--name List.foo` declares `theorem List.foo` in
+it), and `--depends` lists the project declarations a node waits on (library lemmas belong in
+the description).
+
+### Experimental
+
+These work in the projects they came from but are less general; see
+[`docs/automation.md`](docs/automation.md):
+
+- **Automation layer**: durable `operation …` workflows run by `lockstep worker`, a results `inbox`,
+  `proof capture|check|prove`, `node finish`, `probe run|replay`, `context`.
+- **Research library**: `lib search|show|list` over a project catalog
+  (`harness/research/catalog.json`).
+- **Certificate layers**: `[layers]` rules for generated proof-module families, and
+  `storage share` for their compiled artifacts.
+
+## Things that cost hours to learn
+
+- **Never `import` the project modules at the top of a `lake env lean --run` script that also
+  calls `importModules` on them.** The script's own import maps the oleans; the second load
+  cannot mmap at the same addresses and reads them into anonymous memory instead (37 GB and a
+  cgroup OOM kill on a project with large certificate modules). The extractor template imports
+  only `Lean`; `main` imports the project.
+- **Never use `importAll := true`** for the extractor environment (30+ GB). A plain import
+  exposes every theorem value in `env.header.moduleData`.
+- **Never run bare `lake build` on big targets.** Lake 5 has no `-j`; two dozen parallel
+  compilers exhaust a 20 GB guard. `lockstep build` builds Lake's out-of-date list one module per
+  guarded invocation first.
+- **`#print axioms` does not finish on large generated proof families** (16 TB read in 3.5 h);
+  the extractor's module-order taint scan with a per-module cache is the audit path.
+- **A module-system core root (`module` header) cannot import plain files.** When the core root
+  uses it, nodes are written in module form from the start, so a proof elaborates against the
+  same imports before and after `lockstep close`.
+- **The elaborator moves parts of a proof into auxiliary declarations** (`foo._proof_1`), so a
+  dependency scan of a theorem's value alone reports the auxiliaries instead of the lemmas they
+  use. The extractor looks through a declaration's own auxiliaries.
+
+## Development
+
+```console
+uv venv .venv && uv pip install -e ".[test,mcp,research]"
+.venv/bin/python -m pytest
+```
+
+Releases follow semantic versioning (0.x: minor versions may break). Changes are listed in
+[`CHANGELOG.md`](CHANGELOG.md). To release, bump `__version__` in `lockstep/__init__.py`, add the
+changelog entry, and push a `vX.Y.Z` tag: `.github/workflows/release.yml` builds the sdist and
+wheel and publishes them to PyPI through trusted publishing.
+
+## License
+
+MIT; see [`LICENSE`](LICENSE).

lean_lockstep-0.1.0/bin/lockstep

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Launcher: prefer the tools/lockstep virtualenv, fall back to the system python3 (core has no dependencies).
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -x "$here/../.venv/bin/python" ]; then
+  exec "$here/../.venv/bin/python" -m lockstep "$@"
+fi
+PYTHONPATH="$here/..${PYTHONPATH:+:$PYTHONPATH}" exec python3 -m lockstep "$@"

lean_lockstep-0.1.0/bin/lockstep-mcp

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# MCP server launcher (stdio).  Needs the `mcp` package: uv pip install -e "tools/lockstep[mcp]".
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+export LOCKSTEP_PROJECT_ROOT="${LOCKSTEP_PROJECT_ROOT:-$(cd "$here/../../.." && pwd)}"
+if [ -x "$here/../.venv/bin/python" ]; then
+  exec "$here/../.venv/bin/python" -m lockstep.mcp_server "$@"
+fi
+PYTHONPATH="$here/..${PYTHONPATH:+:$PYTHONPATH}" exec python3 -m lockstep.mcp_server "$@"

lean_lockstep-0.1.0/docs/automation.md

@@ -0,0 +1,130 @@
+# Automation layer (experimental)
+
+The automation layer runs multi-step work (proof checks, tactic attempts, finite searches, the
+finish of a node) as durable *operations* that `lockstep worker` executes through the same guarded,
+budgeted jobs as `lockstep job run`. It calls no model: whichever agent submits an operation reads
+the result later, so it works the same for every client. Nothing in this layer establishes a
+theorem: only the compiled Lean environment, `lockstep extract` and the audit do.
+
+Every command here is also an MCP tool. Results are compact by default; large fields are stored
+as immutable SHA-256 artifacts and referenced by id (`lockstep artifact show ID --offset N`, or repeat
+the command with `--full`).
+
+## Operations
+
+```console
+lockstep operation submit --spec work.json [--key IDEMPOTENCY_KEY]
+lockstep operation show OP_ID          # stage, stages_done, stages_total, receipt references
+lockstep operation list
+lockstep operation resume|retry|cancel OP_ID
+lockstep operation reconcile           # detect dead runners without replaying uncertain effects
+```
+
+A spec is a finite list of uniquely named stages, each with a memory cap and a time limit
+(defaults: `[jobs] default_memory_max`, 10 minutes):
+
+```json
+{"schema_version": 1, "stages": [
+  {"name": "sweep", "action": "command", "argv": ["python3", "scripts/sweep.py"], "memory": "2G", "minutes": 30}
+]}
+```
+
+- Stages run in order; a stage that succeeded is never rerun by `resume` or `retry`.
+- Submission is idempotent per agent: the same spec (or the same `--key`) returns the existing
+  operation.
+- Admission is atomic against the shared memory budget (`[jobs]`), so concurrent workers never
+  overcommit. A request that can never fit is reported as `blocked_resource`.
+- Cancellation is a request; the operation counts as cancelled once the owning worker confirms
+  the process is gone. A runner that died mid-stage becomes `unknown_execution` and is never
+  replayed automatically.
+- `lockstep resources reconcile` releases a memory reservation only after confirming its cgroup stopped.
+
+Restart `lockstep worker` after upgrading the harness, so that it runs the current code.
+
+## Results inbox
+
+A finished operation leaves an event in its submitter's inbox (keyed by `LOCKSTEP_AGENT`):
+
+```console
+lockstep inbox list
+lockstep inbox claim --consumer ID     # lease one event (at-least-once delivery)
+lockstep inbox ack EVENT_ID --consumer ID
+lockstep inbox pause|resume            # stop or restart delivery; compute continues
+```
+
+The inbox wakes nobody. A client that wants push delivery polls `inbox claim`, or keeps its turn
+open with `lockstep job wait`.
+
+## Proofs
+
+```console
+lockstep proof capture NODE [--start BYTE --end BYTE]    # freeze the proof span and its source/dependency identities
+lockstep proof check FIXTURE_ID --body body.lean [--memory 4G --minutes 10]
+lockstep proof prove FIXTURE_ID [--tactics omega simp ...]
+lockstep node finish NODE --body body.lean [--extract-memory 16G]
+```
+
+- `proof capture` records the exact UTF-8 byte span of a node's proof plus hashes of the source
+  file, its compiled dependencies and the toolchain. Any later change to them requires a recapture.
+- `proof check` compiles the candidate in a network-less `bwrap` sandbox that sees only the
+  compiled libraries and the toolchain, then audits the whole parent declaration in a separate
+  Lean process. Without `bwrap` it refuses rather than falling back. Failed checks return bounded
+  error headers with byte offsets into the full diagnostic artifact.
+- `proof prove` tries a fixed portfolio of tactics (`rfl`, `simp`, `simp_all`, `omega`,
+  `norm_num`, `ring`, `linarith`, `nlinarith`, `positivity`, `grind`, `aesop`) and stops at the
+  first one the kernel accepts.
+- `node finish` checks the claim, branch and statement lock, checks the candidate, substitutes
+  only its proof span, rebuilds the original module, runs a full extraction and the audits, and
+  writes a reviewable diff. It never commits or publishes (`--policy review` is the only policy).
+
+## Finite probes
+
+A probe is a finite computation (a search for a counterexample, a bounded enumeration) run by a
+project plugin registered in `harness/config.toml`:
+
+```toml
+[research.plugins.my_search]
+module = "harness.research.my_search"        # a module in the project
+sources = ["harness/research/my_search.py"]  # hashed at admission; a change refuses the run
+semantics = ["my-search-v1"]                 # the spec must name one of these
+```
+
+The module provides `evaluate(spec) -> dict` (with an optional `witness`) and
+`replay(witness) -> {"replayed": bool, ...}`. A spec names the plugin, its semantics and a
+positive case and time budget:
+
+```console
+lockstep probe run --spec probe.json
+lockstep probe replay RESULT_ARTIFACT_ID      # recompute a saved witness independently
+```
+
+A witness is replayed before the result is stored. A probe result never closes or refutes a
+node: a counterexample still needs a Lean refutation, and a bounded negative proves nothing.
+
+## Context and the research library
+
+- `lockstep context NODE [--previous BUNDLE_ID]` returns a content-addressed bundle with the node, its
+  source hash, the signatures of the declarations it uses, recent events and operations, and
+  whether the index is fresh. With `--previous` it returns only what changed.
+- `lockstep lib search "TASK"`, `lockstep lib show ID` and `lockstep lib list` search the project's curated catalog
+  of reusable code, `harness/research/catalog.json`: `schema_version: 1` and a list of entries
+  with `id`, `kind` (`primitive` or `workflow`), `title`, `summary`, `api`, `example`,
+  `semantics`, `keywords` and an optional `source`. The symbols a source lists are checked by
+  parsing it, never by importing it. A miss is a reason to search the source, not evidence that
+  nothing exists.
+
+## Certificate layers and the artifact cache
+
+For projects with large generated proof modules (SAT certificates, for example):
+
+- A `[layers]` entry can mark a layer as generated, pin its member list, and freeze the
+  hand-written import closure it depends on; `lockstep layers` enforces this. `lockstep layers
+  --allow-rebuild` accepts changes to those inputs, and the Claude Code hook passes it for a
+  commit whose message carries `[certificate-rebuild]`.
+- `[build.artifact_cache]` and `lockstep storage share` verify byte-identical compiled artifacts and
+  hard-link them through Lake's immutable cache, which saves disk across worktrees.
+
+## Index shadowing
+
+`lockstep index shadow` merges an incremental update of the index and compares it with a supplied full
+extraction. It checks incremental extraction and never publishes an index.

lean_lockstep-0.1.0/examples/minimal/.gitignore

@@ -0,0 +1,2 @@
+.lockstep/
+.lake/

lean_lockstep-0.1.0/examples/minimal/AGENTS.md

@@ -0,0 +1,7 @@
+# Working rules
+
+- Export a stable `LOCKSTEP_AGENT=<client>:<session id>` in every shell; claims, jobs and log entries are recorded under it.
+- Project state comes from `lockstep status`; pick work with `lockstep ready`.
+- Run `lockstep claim <node> --why "<plan>"` before starting, and `lockstep release <node> --outcome ... --note ...` when you stop.
+- New statements go in only through `lockstep node add`; never edit a statement by hand.
+- Commands that run longer than a minute go through `lockstep job run --why "<purpose>" --out runs/<dir> -- <command>`.

lean_lockstep-0.1.0/examples/minimal/Demo/Basic.lean

@@ -0,0 +1,6 @@
+namespace Demo
+
+/-- A core lemma that blueprint nodes can build on. -/
+theorem double (n : Nat) : n + n = 2 * n := by omega
+
+end Demo

lean_lockstep-0.1.0/examples/minimal/Demo.lean

@@ -0,0 +1 @@
+import Demo.Basic

lean_lockstep-0.1.0/examples/minimal/DemoBlueprint.lean

@@ -0,0 +1,2 @@
+-- Root of the DemoBlueprint library: imports every node module.
+-- Maintained by `lockstep node add` / `lockstep node retire`; do not edit by hand.

lean_lockstep-0.1.0/examples/minimal/harness/allowlist.json

@@ -0,0 +1 @@
+[]