docs: one canonical handoff, rewritten in place; F-035

Handoff documents were additive. HANDOFF-2026-08-19 opened by saying the
18 AUG document still applied in full and added to it. After ten sessions
a new assistant would face ten documents to read in date order and diff
mentally to work out what is currently true. That cost grows every
session and none of it is necessary.

docs/HANDOFF.md is now the only handoff, rewritten in place each session.
It is state, not a log. The dated ones move to docs/archive/ and stop
being required reading. It is standalone: everything still true from both
is carried forward.

Section 1 is invocation, stated as facts rather than demonstrated in
examples. That is the other half of the problem. runuser appeared only
inside example commands, so it could be learned by pattern matching but
not by reading, which fails exactly when an assistant composes a command
from scratch. That is what happened, and it is F-035: su cannot run as a
nologin service user, both commands returned the same message before
touching anything, and the output read as a broken repository when the
tree was clean and the suite passed. The F-027 class again.

Also stated as facts: bash tools/ not ./tools/, all repository operations
as mechcomp, Gitea SSH on 42022, pct push then chown, explicit timeouts,
journalctl not /var/log, systemd-run for long jobs, and assert the guest
is running before interpreting any pct exec result.

Not done: the same facts should be cross referenced from PROCESS.md. I no
longer had that file in view and would not patch a document I cannot see.
This commit is contained in:
2026-08-19 12:33:50 -05:00
parent 009fcce61c
commit af196a26f5
4 changed files with 438 additions and 0 deletions
+239
View File
@@ -0,0 +1,239 @@
# HANDOFF — 2026-08-18
For the assistant taking over. Read this, then the documents it points to.
---
## 1. Read these first, in this order
All in `mechanical-compiler/docs/` at commit `6967eef5`.
| # | File | Why |
|---|---|---|
| 1 | `PROCESS.md` | How work is done here. Read before issuing any command. |
| 2 | `STAGING-STATE.md` | What is true on `srv-b` right now |
| 3 | `FAILURES.md` | What has already gone wrong. 32 entries. |
| 4 | `ENVIRONMENT.md` | The specification, revision 5.3 |
| 5 | `ROADMAP.md` | Where the project is going, and 16 standing principles |
If you are writing provisioning automation, read `FAILURES.md` **before** the
specification. Every entry is something a script written from the specification
alone would have got wrong.
**Authority when documents disagree:** `STAGING-STATE.md` wins on facts.
`FAILURES.md` is evidence. `ENVIRONMENT.md` is corrected when proven wrong.
---
## 2. The operator's constraint
**CIVICVS has a shell on `srv-b` and a browser-based file manager. Nothing
else.**
No workstation git client. No direct container shell. No IDE. No `scp`. Files
arrive by upload to `/root/incoming` on `srv-b`; every command runs in that one
shell.
Everything below follows from this. An assistant that assumes otherwise
produces instructions the operator cannot execute — which has happened more
than once, including to me.
---
## 3. How I failed the operator, so you can avoid it
This section matters more than the status. Four specific failures, all mine.
### Multiple instructions in one message
The single most repeated complaint, and the one that ended the session.
**One task. One command group. Wait for output.** Not "here are three things
you could do next." Not a numbered procedure spanning several systems. Not a
task with two optional extras attached.
If you find yourself writing "and also" or offering a choice of next steps,
delete it. Ask which one, or pick one and do it.
### Referring to things the operator cannot see
I wrote `cd /path/to/srv-b-host` for a repository that exists only in Gitea,
uploaded through a web form. There was no path. The operator was right to
object that if I did not know it, he had no reason to.
**Never write a placeholder path.** If you do not know where something is,
ask — as one question, on its own.
### Raising things that do not matter
I flagged a file mode bit in Gitea that could not be fixed from the web
interface, was not worth a clone, and did not affect anything. It cost a full
exchange of confusion.
**If a finding is not actionable and not important, do not raise it.** The
operator's attention is the scarce resource.
### Asserting from a proxy observation
I stated that CT 100 and CT 101 had no mail agent, based on inspecting Postfix
configuration **on the host**. I then "standardised" CT 102 against that belief.
The first run of `ct-baseline.sh` showed both containers had mail agents. See
F-031.
**Check the thing, not something adjacent to it.**
---
## 4. Where things stand
### Infrastructure — complete
`srv-b`, Proxmox VE 8.4.0, standalone. Three containers, all conforming.
| CT | Name | Address | Role |
|---|---|---|---|
| 100 | `mechcomp` | `10.20.0.10` | application, worker |
| 101 | `mcproxy` | `10.20.0.11` | reverse proxy, TLS |
| 102 | `kane-fabric` | `10.20.0.12` | **separate project** |
All on `vmbr1`, a portless service bridge. `srv-b` is router and bastion:
internet → WireGuard → `srv-b` → containers. Containers cannot reach the home
LAN. Containers cannot send mail — only `srv-b` does, and only its own alerts.
Working and proven: TLS termination with `X-Forwarded-Proto` reaching the
backend, mail delivered end to end, `smartd` monitoring four drives with
alerts received, SMTP egress blocked, host-reboot persistence.
### Conformance
`ct-baseline.sh` — read-only, run any time, exits non-zero on divergence.
Installed at `/usr/local/sbin/ct-baseline.sh`. Canonical copy in
`TheRON/srv-b-host`.
**A property not checked by it is not part of the standard.** That is what
makes conformance terminate rather than recur. Last run: 62 passed, 0 failed.
### Repository — seeded
`mechanical-compiler` at `6967eef5`. CT 100 has a working clone at
`/var/www/mechcomp`, owned by `mechcomp`, pushing over SSH with deploy key
`srv-b-ct100`. **Gitea SSH is on port 42022.**
Dependencies installed. Oracle verifies in-container. `3 passed, 236 skipped`.
### Backup — deliberately not done
Not an oversight. The operator's reasoning, which is correct: a backup of an
unverified configuration restores the confusion along with the data. A backup
taken before 2026-08-18 would have preserved two containers that queue mail
forever.
**Entry condition: `ct-baseline.sh` exits 0.** Do not raise this again until
there is something worth preserving. The documents are in Gitea; nothing else
currently exists whose loss would cost more than an afternoon.
---
## 5. The next work item
**Port `sb-geom` to Shapely.** Get `pytest -n auto` green against the 123
frozen cases in `fixtures/strap-beam-8.0.0/`.
This is development mode, not infrastructure mode — see `PROCESS.md` §2. Do not
apply command-group ceremony to a test-fix-rerun loop.
`tests/test_oracle.py` already specifies the API. It was written before the
port, deliberately, so the interface follows from what must be verified:
```python
build(family, profile, params) -> Result # Result.report -> dict of SB_* keys
ProfileRejected # str() names the parameter and the limit
```
**The ten rejected cases are part of the contract.** A port that accepts them
is wrong however good its numbers are elsewhere. The harness was proven by
adversarial stub: a `build()` that rejects everything passes all 10 rejection
tests and fails all 226 acceptance tests.
An untried gate that should be run first:
```
make toolchain
./tools/reference-toolchain/verify.sh --full
```
That regenerates all 123 cases inside the pinned image and diffs against the
committed oracle. Slow — single-threaded solvers on 2010 Westmere cores. Expect
a one-line difference in the `frozen` date; anything else means drift.
---
## 6. Open questions, none blocking
| # | Question | Owner |
|---|---|---|
| 1 | Should `wg-pk` narrow `mynetworks` from `10.110.0.0/22` to explicit hosts? | CIVICVS, estate decision (F-025) |
| 2 | Backup strategy — USB, IPFS, optical? | CIVICVS |
| 3 | Where is the 3+ TB USB disk attached? | CIVICVS |
| 4 | Kane Fabric participant mail — send and receive, unsolved | Cross-project |
Question 4 is real and unaddressed. Containers do not send mail by standard,
and nothing can reach `vmbr1` from outside, so receiving has no path at all. It
needs a design conversation, not a configuration change.
---
## 7. Things that will bite you
- **Gitea SSH is port 42022.** Remotes need `ssh://git@host:42022/owner/repo.git`
— the `git@host:path` shorthand cannot carry a port.
- **Deploy tokens in Gitea are account-level**, under user Settings. Repository
settings offer deploy **keys** only. I got this wrong twice.
- **The service user's home is the install directory**, so anything writing to
`$HOME` writes into the working tree. `.cache/`, `.local/`, `.ssh/` are all
in `.gitignore` for that reason (F-029).
- **Every network command needs an explicit timeout.** One without hung the
operator's shell (F-030).
- **`journalctl`, not `/var/log/mail.log`.** Proxmox ships without `rsyslog`
(F-024).
- **Assert health after a *host* reboot**, not a guest reboot. Different
machinery (F-026).
- **A test must distinguish tool failure from the condition it tests.** A
`pct exec` that fails because the container is stopped will otherwise read as
a pass (F-027).
---
## 8. What the project is for
Not required to do the next work item, but it is why any of this exists.
Build the capacity to construct real structures — the reference case is a
faceted timber shell — from reclaimed and commodity materials, using whatever
fabrication is to hand. The compiler makes the pieces computable, qualifiable,
and reproducible by someone who was not present when they were designed.
**Codes and permitting are out of scope, deliberately.** The project records
physical claims, never verdicts. Measure and attest; never adjudicate.
Three artifact classes: **members** (prismatic, exist — the eleven profiles),
**nodes** (non-prismatic, no representation yet), **panels** (sheet, none yet).
The gap that moves next in priority is dihedral parameterisation: if two panels
meet at 137°, none of the eleven profiles gives you a member for it.
---
## 9. Working with this operator
He is precise, keeps excellent records, and will tell you directly when you are
wrong — including when you are being unhelpful. Take that at face value; it is
accurate and it is not personal.
He decides. Bring evidence and a recommendation, then stop.
Do not re-litigate settled decisions. Webmin is installed on every node and is
his only remote access to `srv-b`; I wasted his time questioning it. Backup is
postponed for good reasons. `4x` is the end of the N-strap family.
When he says he does not understand something, the writing was unclear. Rewrite
it shorter, do not explain it again at greater length.
+237
View File
@@ -0,0 +1,237 @@
# HANDOFF — 2026-08-19
For the assistant taking over. Read this, then the documents it points to.
The 18 AUG handoff still applies in full: the operator's constraint, the working
discipline, and everything in §7 "Things that will bite you". This document adds
what one session of actual porting established. It does not replace it.
---
## 1. Read these first, in this order
All in `mechanical-compiler/docs/` at commit `86a47c3`.
| # | File | Why |
|---|---|---|
| 1 | `HANDOFF-2026-08-18.md` | Still current on process, constraints, and hazards |
| 2 | `PROCESS.md` | How work is done here. Read before issuing any command. |
| 3 | `FAILURES.md` | 34 entries now. F-033 and F-034 are from this session. |
| 4 | `STAGING-STATE.md` | What is true on `srv-b` |
`ENVIRONMENT.md` and `ROADMAP.md` as needed. The port work is development mode,
not infrastructure mode — see `PROCESS.md` §2.
---
## 2. Where the port stands
**The entire shared layer is ported, tested and pushed.** Six slices, each
committed separately with its own tests, each proven by mutation before landing.
| Module | From | What it holds |
|---|---|---|
| `geom/primitives.py` | `sb-geom.scad` | Vectors, GEO and MEMBER, sleeve and cavity paths, exact polyline distance, corner-radius derivation, the monotone solver |
| `geom/rounding.py` | BOSL2 `92d697c2` | `round_corners`, `_circlecorner`, `arc`, `segs`, `deduplicate`, `path_merge_collinear` |
| `geom/region.py` | BOSL2 regions | Shapely-backed booleans, nesting-parity decomposition, area, simplicity, hull, mitred offset, cleaning |
| `geom/join.py` | `sb-join.scad` | Butt joints, hull caps, fillets, the derived bore, ring fit, section assembly |
| `geom/report.py` | `sb-report.scad` | Checks-as-values, metrics, the five universal checks, `ProfileRejected`, report formatting |
| `geom/core.py` | `sb-core.scad` | The PROFILE record, failure representation, centred assembly |
| `geom/arrangements.py` | `sb-profiles.scad` | The three N-generic arrangements: ring, spokes, fins |
**230 unit tests, none of which touch the oracle.** The 236 oracle acceptance
tests still skip: `mechcomp.profiles.build` does not exist yet.
### What remains
Read `strap-beam-3x.scad` and `strap-beam-4x.scad`. Port the eleven catalogue
profiles and the `build()` entry point into `src/mechcomp/profiles/`. Then the
oracle runs for the first time.
**The port's public entry point is `mechcomp.profiles`, not `mechcomp.geom`.**
`conftest.py` does `importorskip("mechcomp.profiles")` and requires a `build`
attribute on it. The geometry lives under `mechcomp.geom`; `build()` and
`ProfileRejected` must be exported from `mechcomp.profiles`.
---
## 3. Things established this session that are expensive to rediscover
### Report values are rounded to six significant figures
The oracle records what OpenSCAD's `echo` printed, which is C's `%g` at default
precision — not full-precision geometry. `echo_num()` in `geom/report.py` does
this; `echo_vec()` handles vectors, which reach the oracle as strings like
`'[20.5209, 20.5209, 20.5209]'`.
This is load-bearing, not cosmetic. `VOLUME_MM3` ends in `_MM3`, so
`test_oracle.py` compares it at the **lengths** tolerance of 1e-4 rather than the
areas tolerance of 1e-3. Volume is section area times a 100 mm length, so an
unrounded port reporting 13557.402 against a recorded 13557.4 fails by twenty
times the tolerance while being geometrically correct.
Verified: across all 113 accepted cases the recorded volume equals the rounded
area times length to within 3.6e-12.
### Angles are degrees, and the arbitrary constants are contract
OpenSCAD trigonometry is in degrees. The port keeps degrees throughout with
explicit `cos_d`/`sin_d`/`tan_d` helpers so every expression matches its source
line. The 44 solver iterations, the 0.999 and 0.98 scale factors, the
0.05/179.95 degree cutoffs and the 1e9 sentinel are reproduced exactly. They are
not tidy numbers to improve on; they produced the frozen values.
### You can probe the reference directly
The pinned toolchain image is in CT 100 and OpenSCAD will echo whatever you ask
it. This turned F-034 from a guess into a measurement in about four exchanges,
and it will settle any later disagreement the same way.
Mount the tree **read-only** and keep the probe on a separate writable mount.
Docker runs as root and a read-write mount against a `mechcomp`-owned tree is
the F-033 hazard. Note that a nested single-file mount inside a read-only mount
fails with `EXIT=125` — put the probe in its own directory instead.
```bash
pct exec 100 -- bash -c 'mkdir -p /tmp/probe && cat > /tmp/probe/p.scad << "EOF"
include </repo/legacy/openscad/lib/sb-core.scad>
$fn = 48;
g = sb_geo(15.875, 0.508, 1, 0.25, 1.20, 1.20, 1.20, 1.20);
echo(str("PROBE=", sb_area([sb_sleeve_path(sb_member(0,0,0), g)])));
EOF
docker run --rm -v /var/www/mechcomp:/repo:ro -v /tmp/probe:/probe -w /probe \
mechcomp/reference-toolchain:8.0.0 \
openscad -o /tmp/o.stl --export-format=asciistl p.scad 2>&1 | grep -E "PROBE|ERROR"'
```
`EXIT=1` is normal — STL export fails on 2D geometry. The echoes still arrive.
The harvester itself exports to `/dev/null` for exactly this reason: the export
only forces evaluation.
### The oracle's parameter defaults
`strap-beam-3x.scad` lines 65–135. Notably `y_junction_round_mm = 1.50`,
`three_fin_junction_round_mm = 2.00`, `ring_corner_radius_mm = 2.00`,
`facets = 48`, `material_density_g_cm3 = 1.24`. All 123 cases run at
`facets = 48`; nothing overrides it.
### Environment facts
Shapely 2.1.2 on GEOS 3.13.1. Shapely is in `requirements-base.txt`, the 2D
path's own dependency set. **No CAD kernel is installed in CT 100** — `cadquery`,
`OCP` and `build123d` are all absent, though `requirements-cad.txt` says it is
installed by default. That is the strictest possible environment for the 2D path
and will matter when STL and STEP export starts.
Git identity is now set `--local` in the clone as `TheRON
<webmaster@kane-il.us>`, matching the two most recent commits. It must stay
local: `mechcomp`'s home **is** the working tree (F-029), so `--global` would
write into the repository.
---
## 4. Verified against the reference
Three-Fin at the oracle's defaults reproduces **every recorded value exactly**,
including `SECTION_AREA_MM2 146.787`, `VOLUME_MM3 14678.7` and `MASS_G 18.2016`.
That case exercises butt joints, `fillet_junctions`, `fillet_pair`,
`fillet_concave`, `round_corners`, the derived bore and the fin solver.
Y reproduces every value except section area and its two derivatives.
Exact across both: `SPOKE_RADIUS_MM 9.1713`, `SPOKE_WEB_MM 1.2`,
`FIN_CORE_SIDE_MM 13.4028`, `FIN_SETBACK_MM 3.77783`,
`FIN_JUNCTION_WEB_MM 2.29919`, `FIN_BORE_SIDE_MM 7.5`,
`RING_CORNER_R_MAX_MM 2.87663`, the ring edge vector, and both envelope
dimensions on both profiles.
**The numerical machinery is right.** Where the port disagrees, it is F-034.
---
## 5. F-034, and the decision it will force
Read the entry in full. The short version:
Arc segment counts are `ceil((90 - half_angle)/180 * $fn)`, and that expression
is frequently an exact integer — a 60° half-angle at `$fn = 48` gives exactly 8.
Floating point delivers it as `8.000000000000004` or `7.999999999999998`
depending on how the corner was reached. The half-angles come from the merged
polygon, whose vertices come from the boolean kernel, and BOSL2's clipper and
GEOS disagree in the last bit.
**Do not try to fix this.** It was tried and reverted. Rounding the count before
the ceiling makes the three symmetric pairs identical and fixes Y exactly — and
breaks Three-Fin, which had been matching to the digit, because Three-Fin has the
same asymmetry and **the oracle records it**.
Two consequences:
**Some recorded values encode float noise rather than geometry.** A port that is
geometrically more correct than the reference will fail those cases.
**The tolerance model may need revisiting, and that is CIVICVS's call.** Any case
affected fails on `VOLUME_MM3` and `MASS_G` long before it fails on
`SECTION_AREA_MM2`, because volume is checked at 1e-4 while being area times
100 mm.
**Do not raise this until `build()` exists and all 123 cases have run.** The
number of affected cases is unknown and is the only thing that should drive the
decision. It may be one case. Bring the count and a recommendation, then stop.
---
## 6. How this session worked, and what to keep
**Read the source, do not recall it.** BOSL2 was fetched at the pinned commit and
read directly — `round_corners`, `_circlecorner`, `arc`, `segs`, `deduplicate`,
`is_collinear`, `vector_angle`. Every one of those had a detail that mattered and
that recollection would have got subtly wrong.
**Mutation-test every suite before landing it.** Break the code deliberately and
confirm the tests notice. This found real gaps five times in six slices:
- nothing exercised BOSL2's three-point floor on blunt corners
- nothing distinguished on-boundary from outside in the nesting probe
- the area guard alone accepts a bore that has turned inside out
- the ring fit really does have a spurious lower branch below scale 1
- nothing asserted that `clean_region` removed anything
It also caught one malformed mutation of mine — cutting the cavities twice is
idempotent — which is worth knowing: a surviving mutation is sometimes a bad
mutation, not a test gap. Check which before writing a test.
**Deliver by upload, not by paste.** `PROCESS.md` §3. A sixty-line heredoc with
em-dashes and nested code fences was mangled by the browser terminal. Everything
since went as a tarball with a stated checksum, file list, and what it
overwrites. That has not failed once.
**One command group per message, and wait.** Every command group in this session
was read-only first where the answer was not certain.
---
## 7. State
Gitea `main` at `86a47c3`. CT 100 clean and matching. Suite: **230 passed, 236
skipped**.
```
86a47c3 rounding: record F-034, arc segment counts tip on the last bit
8d79431 geom: port sb-core and sb-profiles, the N-generic arrangements
b101fe6 geom: port sb-report, validation and report formatting
ebf02d6 geom: port sb-join, the junction and envelope strategies
38ea024 geom: Shapely-backed region layer
545eee7 geom: port BOSL2 round_corners and path cleanup
dfd02a4 geom: port the pure-geometry half of sb-geom
b67cc12 verify.sh: reach the restore on the diff branch
1d3eed0 Handover push
```
The toolchain gate passed at the start of this session: all 123 cases regenerate
byte-identically inside the pinned image, 113 accepted and 10 rejected, the only
diff being `frozen` and the hash containing it. The oracle is a stable target.
`verify.sh --full` exits 1 by design on any diff, and the `frozen` date
guarantees one. That is a pass, not a fault. Its restore path was broken and is
now fixed but **still unexercised** — see F-033. The next `--full` run proves it.