This is the directory and file-placement guide for MathTrace. For development changes and governance, read AGENTS.md and use the OpenSpec specifications. For a mathematical campaign, use the owned root protocol and that campaign's .math state. For choosing an interactive skill, read the generated skill guide.
| Location | Owner and contents | Purpose / When to use |
|---|---|---|
mathtrace/ |
Authoritative Python runtime, CLI, and Lean helper; pyproject.toml owns packaging/CLI entry configuration |
Changing runtime implementation. |
tests/ |
Developer regression tests and explicit fixtures | Checking changed runtime invariants and regression coverage. |
tools/ |
Developer installation, setup, and validation helpers | Running package validation, native projection installation, and toolchain checks. |
docs/ |
Operational guides, workspace map, and architectural decisions | Documenting system behavior, operations, and historical decisions. |
openspec/ |
OpenSpec specifications (specs/), change proposals (changes/), and configuration |
Specifying system capabilities and managing project changes via OpenSpec. |
.agents/ |
Generated native roles, skills, protocol/help/config and OpenSpec skills | Generated and managed via tools/install_native.py; preserves OpenSpec skills and workflows. |
.math/ |
Per-campaign immutable records/events and derived current eligibility | Running mathematical research through the runtime; created when a campaign is initialized. |
work/validation/ |
Retained observations, fixtures, exact receipts, and local checking environments | Storing validation runs and checking environments. |
work/archives/ |
Managed projection recovery snapshots | Storing verified native projection backups created by the installer. |
work/provenance/ |
Historical comparison and provenance material | Preserving upstream source provenance. |
build/, *.egg-info/, .pytest_cache/, __pycache__/ |
Generated build copies, metadata, and caches | Temporary build and test caches created by tools. |
AGENTS.md owns development governance. openspec/ owns all capability specifications and change workflows. Historical architectural decisions and review dispositions are preserved in docs/architecture/decisions.md.
| Guide | Scope |
|---|---|
| Coordination | Adaptive frontier, work intents, route/obligation lineage, terminal intake |
| Evaluation | Scoped support/refutation, assumptions, selected witnesses, and currentness |
| Evidence | Computation/Lean plans, actual receipts, compiled fidelity, and assurance limits |
| Execution | Durable intent, observed completion, recovery, and explicit reruns |
| Native capture | Native attribution, exact input admission, and host limits |
| Completion | Exact requested outputs, fulfillment/delivery, and retained negative reports |
| Learning | Local advisory extraction, curation, target admission, and revocation |
| Decisions | Preserved historical architectural decisions, sibling audits, and assurance bounds |
Run from the workspace root; read each helper's scope before executing it:
| Helper | Purpose and effects |
|---|---|
tools/install_native.py |
Verify ownership, archive previous projection, regenerate .agents/ preserving external skills, and update work/native-install.json |
tools/validate_package.py |
Build and install an isolated wheel, verify source/helper bytes and CLI identity, retaining packaging evidence |
tools/setup_execution.py |
Provision the optional pinned Linux isolation backend (Bubblewrap); native execution needs no sandbox setup |
tools/validate_lean.py |
Explicit Lean boundary fixtures against the provisioned validation database |
tools/validate_canonical_formal.py |
Isolated ordinary-module receipt and invalidation fixtures |
tools/probe_compiled_semantics.py |
Specialized unmocked semantic-channel prototype evidence |