TheRON
15e90fd8cf
New section 3a records the whole path from an assistant producing something to it existing in Gitea. It has been explained conversationally to every new assistant for months and was written in no document, which is the reason it is now here. Section 0 claims this document describes how work gets done; the part it did not describe was how work actually arrives. 3a covers: nothing but the operator writes, because the assistant reads Gitea read-only and the operator is the only party with write access anywhere in the chain. Three command groups rather than one, because section 4 requires a suite result the assistant has actually seen before a commit exists. The shell-free idioms - make -C, git -C, runuser - because pct exec runs no shell. Commit messages parsed by the host shell before pct sees them, so repeated -m flags and no dollar sign, backtick or exclamation mark. Which failures are passes, because an operator who cannot tell success from failure cannot report usefully. 3a also records the amendment rule: do not ship a rewritten file to change a few passages of a large one. Ship an anchored script that validates every anchor matches exactly once and writes nothing if any does not. This commit was made that way. A rewrite regenerates the document from the assistant reading of it and a transcription error is silent - the same hazard as rewriting HANDOFF.md in place, one level down. Section 4: the oracle check and git status are one check, not two (F-033). And the two interpreters are deliberate - verify-oracle runs python3 because make_fixtures.py imports nothing outside the standard library, test runs venv/bin/python because the suite imports mechcomp, Shapely and pytest. Neither is a mistake to be tidied into consistency. Section 8: the reading order was missing HANDOFF.md for three weeks while HANDOFF section 0 carried a different order missing ENVIRONMENT.md. Two lists, neither complete, each looking authoritative. Both now name DIVERGENCES.md. The authority ladder gains the rule underneath it: a document that describes something yields to the thing it describes, a document that prescribes something does not. That dissolves the apparent contradiction with deploy/README.md, which is correct to claim the repository wins for the files it owns. Section 8 also qualifies promote-the-deviation. It applies to facts about a host, not to a requirement the code has not met. A REQ is never lowered to match what was built; the gap is recorded in DIVERGENCES.md and the correction is owed by the code. A specification that agrees with whatever exists specifies nothing. Section 10 described 18 AUG: repository at its seed commit, port not started, 3 passed and 236 skipped. It now states that it no longer records a commit, a version or a test count, because git rev-parse, git describe and make test report those and every attempt to hold them current in prose went stale. Suite 643 passed, oracle intact at 113 accepted and 10 rejected. Documentation only.
Mechanical Compiler
Build the capacity to construct real structures from reclaimed and commodity materials, using whatever fabrication is actually to hand — 3D printing, tabletop CNC, welding, cement casting, COTS stock.
The reference case is a faceted timber shell: planar panels meeting along straight fold lines, converging on nodes, sitting on a platform. Buildable without a factory, provided someone has worked out what the pieces are and how they meet. That last clause is the project. The Mechanical Compiler exists to make the pieces computable, qualifiable, and reproducible by someone who was not present when they were designed.
Scope
In scope: geometry, qualification, and reproducibility of structural members and their interfaces.
Not in scope: building codes, permitting, jurisdictional approval. Qualification and compliance are different things. A qualification says this member is what it claims to be, made this way, from this stock. Compliance is a jurisdiction-specific argument someone else may build on top.
The project records physical claims, never verdicts — section modulus, moment of inertia, material provenance, process parameters. Those are what any future argument would need. A pass/fail verdict would bake in a jurisdiction we do not want to be bound to. Measure and attest; never adjudicate.
Repository layout
docs/ specification, state, failure log, roadmap
legacy/openscad/ rev 8.0.0 generators — reference, not a live target
fixtures/ frozen acceptance oracles
tools/reference-toolchain/ pinned OpenSCAD + BOSL2, build-time only
src/mechcomp/ the application
tests/ acceptance against the oracle
Read docs/ROADMAP.md first for what this is, then docs/ENVIRONMENT.md for
how an instance is built. If you are writing provisioning automation, read
docs/FAILURES.md before the specification — every entry is something a
script written from the specification alone would have got wrong.
Getting started
make deps # virtualenv, base + CAD requirements
make verify-oracle # confirm the frozen oracle is intact
make test # pytest -n auto
make verify-oracle needs nothing but Python. It should pass on any machine at
any time; if it does not, stop.
The oracle
fixtures/strap-beam-8.0.0/ holds 123 frozen cases — 113 accepted, 10
rejected — produced by OpenSCAD 2021.01 with BOSL2 at 92d697c2. It is the
acceptance criterion for any reimplementation of the generators.
The ten rejected cases are part of the contract. A port that accepts them is wrong, however good its numbers look elsewhere. It is easy to reproduce the geometry and quietly lose the constraint that made it trustworthy.
The generators under legacy/openscad/ are the reference implementation, kept
so the oracle can be regenerated. They are not a live target and the running
application has no OpenSCAD dependency.
Provenance
This project's documents, code and roadmap are LLM-generated under human direction. That is stated plainly here and in any downstream submission. We do not obscure it.
The maintainer reviews and owns every line. Anything that could not be defended in a review thread does not ship.
Licence
AGPL-3.0-or-later. See LICENSE.
Section 13 obliges us to offer source to users interacting over a network, so any deployed web tier carries a visible link back to this repository. That is a licence obligation, not a courtesy.