diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 6550303..3830d7e 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -6,7 +6,7 @@ It is the only handoff you need to read. Dated handoffs in `docs/archive/` are historical and are not required reading — do not diff them against this to work out what is true. If something here is wrong, correct it here. -Last updated 2026-09-12, after the identity contract and the gate register landed. +Last updated 2026-09-13, after the documentation audit. This line used to carry the commit hash of its own rewrite. It cannot: the hash is not known until the commit is made, so the value was always the @@ -26,12 +26,17 @@ This document is not the first thing to read, despite being the handoff. 2. **`docs/STAGING-STATE.md`** — what is true on the host right now. 3. **`docs/FAILURES.md`** — what has already gone wrong and why. 4. This document — where the code stands. -5. `docs/ACCEPTANCE.md`, `docs/STOCK.md`, `docs/PRECISION.md` — the +5. **`docs/DIVERGENCES.md`** — requirements that stand and are not met. +6. **`docs/ENVIRONMENT.md`** — the specification an instance is built to. It was + missing from this list for three weeks while `PROCESS.md` §8 carried it and + omitted this document instead, so a successor following either list alone + missed something. Both lists now carry both. +7. `docs/ACCEPTANCE.md`, `docs/STOCK.md`, `docs/PRECISION.md` — the specifications the code is held to. -6. **`docs/IDENTITY-CONTRACT.md`** — how a visitor's identity arrives, and the +8. **`docs/IDENTITY-CONTRACT.md`** — how a visitor's identity arrives, and the boundary that keeps membership out of this application. The only document here written to be read by someone who does not work on this repository. -7. `docs/CONSUMER_INTERFACE_GATES.md` — cross-project concerns that are open, +9. `docs/CONSUMER_INTERFACE_GATES.md` — cross-project concerns that are open, with owners. Non-normative. **Read it before proposing any integration with a membership or geography system**; several tempting ones are recorded there as things to specifically not build yet. @@ -165,7 +170,9 @@ internet → WireGuard → `srv-b` → containers. Containers cannot reach the h LAN and cannot send mail. `ct-baseline.sh` is read-only, runs any time, exits non-zero on divergence. -Installed at `/usr/local/sbin/`. Last run: 62 passed, 0 failed. **A property it +Installed at `/usr/local/sbin/`. **Last run 2026-08-18: 62 passed, 0 failed — +which predates the DNAT rule and the placeholder service replacement, both of +which `PROCESS.md` §9a names as requiring a run. Overdue. See DIV-006.** **A property it does not check is not part of the standard** — that is what makes conformance terminate rather than recur. @@ -193,11 +200,18 @@ terminate rather than recur. ### The port — COMPLETE -Gitea `main` at `ee3fedf` before this commit. CT 100 clean and matching. +The suite is green and the composer is live. -**Suite: 547 passed, 0 failed.** The 30 expected failures are gone, resolved -rather than suppressed, by the tolerance model in `docs/ACCEPTANCE.md`. A red -`make test` now means something is actually wrong. +**This section no longer records a commit hash or a test count.** +`git rev-parse HEAD` and `make test` report them. The line that used to carry +the hash was always the *previous* commit — the hash is not known until the +commit is made — which is how this section drifted two behind without anyone +noticing, exactly as the header says of its own date. Both are now derived +rather than transcribed. + +The 30 expected failures are gone, resolved rather than suppressed, by the +tolerance model in `docs/ACCEPTANCE.md`. A red `make test` now means something +is actually wrong. **The composer is live.** `mechcomp.service` in CT 100 serves it on `10.20.0.10:8770`, behind nginx on CT 101, proven `HTTPS 200` end to end. @@ -220,7 +234,8 @@ rather than suppressed, by the tolerance model in `docs/ACCEPTANCE.md`. A red | `stock.py` | — | COTS stock descriptor: `RectStock`, `RoundStock`, `Fit`, `Provenance`. A leaf module — imports nothing from `mechcomp`. See `docs/STOCK.md` | | `design_record.py` | — | What a model was made from, at full precision, sufficient to regenerate it. `input_id` and `build_id`, and `Author` — recorded, rendered with its own limit, and in neither hash | | `svg.py` | — | Cross-section as SVG, separately classed layers for material, cavities and stock | -| `web/app.py` | — | The composer. Standard library HTTP server; binding from `/etc/mechcomp/mechcomp.env` | +| `stl.py` | — | A member as a sealed binary mesh: two triangulated caps and a quad strip down the boundary. **No CAD kernel** | +| `web/app.py` | — | The composer. Standard library HTTP server; binding from `/etc/mechcomp/mechcomp.env`. Serves `/`, `/api/build` and `/m/stl` | `make deps` is complete in CT 100 and **must not be re-run**. @@ -264,19 +279,23 @@ so a successor can disagree with the argument rather than only the sequence. The person is identified by an email address. A handle may be chosen later and does not replace it. Nothing verifies the address and the record says so on the line it appears on. -2. **STL export.** No new dependency, no kernel, and it is the only item that - produces *physical* feedback. Everything so far is verified against a frozen - oracle; a printed coupon is the first test against reality, and the first - real measurement of whether `fit_clearance_mm` suits the operator's printer. - The composer already makes stock, fit and walls configurable, which was his - stated precondition for printing anything. +2. **STL export. Landed at `0545b79`; the bounded export route at `cdde394`.** + No new dependency and no kernel — a member is prismatic by definition, so an + STL is two triangulated caps plus a quad strip down the boundary. It was the + only item producing *physical* feedback: everything else is verified against + a frozen oracle, and a printed coupon is the first test against reality, and + the first real measurement of whether `fit_clearance_mm` suits the operator's + printer. - **`length_view` is not in `COMMON_GROUPS`.** The Full Length branch is - therefore unreachable from the composer, so every export would silently be a + **`length_view` was missing from `COMMON_GROUPS`**, which would have made the + Full Length branch unreachable from the composer and every export a silent 100 mm preview — a file that looks right, slices right, and is the wrong - object. The sweep must be `model_length_mm(p)`, the value already published - as `LENGTH_MM`, or the record's `VOLUME_MM3` and `MASS_G` describe something - other than the file beside them. That control has to exist first. + object. Fixed before the route shipped. The sweep is `model_length_mm(p)`, + the value already published as `LENGTH_MM`, so the record's `VOLUME_MM3` and + `MASS_G` describe the file beside them rather than something else. + + `/m/stl` ships **open**, because `/m/` is not yet gated and no membership + system exists to gate it. Carried as open question 10 rather than justified. 3. **Per-member stock — the conduit core.** What CIVICVS asked for on 22 AUG and still cannot be done: `Geo` is global to a build, so every member is the same rectangular strap by construction. Reaches into `join.py` and @@ -327,10 +346,10 @@ Roadmap items — read `ROADMAP.md` before starting any: Moving stock from the build to the placement reaches into `join.py` and `arrangements.py`, and it is the first change where the oracle's own geometry is genuinely at risk rather than merely nearby. -- **The composer, deepened.** It exists and serves; it does not export - anything, persist anything, or show a bill of materials. `payload["defaults"]` - is sent to the browser and nothing reads it — dead weight, and it is what - made a verification grep lie on 11 SEP. +- **The composer, deepened.** It exists, serves, and exports STL; it does not + persist anything or show a bill of materials. `payload["defaults"]` is sent to + the browser and nothing reads it — dead weight, and it is what made a + verification grep lie on 11 SEP. - STEP export. Needs a CAD kernel and none is installed in CT 100 (§5). STL needs none — a member is prismatic by definition. See §5. - `mechcomp-worker.service`. `src/mechcomp/worker/` is still a 36-byte stub and @@ -516,9 +535,15 @@ and the oracle records it. There is nothing to correct on the port's side. ×100, mass is volume ×density/1000, so each case has **one** discrepancy reported three times. **Worst relative error 2.24e-05.** -By profile: Three-Fin 9, Y 7, A Frame 5, Rectangle 5, T 1, Four-Fin 1. None on +By profile: Three-Fin 10, Y 7, A Frame 6, Rectangle 5, T 1, Four-Fin 1. None on Equilateral, General Triangle, Square, Diamond or Cross. +An earlier version of this line read Three-Fin 9 and A Frame 5, summing to 28 +against the stated total of 30. Measured and corrected — `docs/ACCEPTANCE.md` +§7 and F-034's resolution carry the same figures. The correction had been +recorded in both of those for three weeks while the wrong numbers stayed here, +in the document a successor reads first. + ### Why the test fails when the geometry is fine At `$fn = 48` a chord deviates from its true arc by `r(1 − cos 3.75°)` = @@ -696,29 +721,11 @@ a design conversation, not a configuration change. ## 12. Commit log -``` -a8081e1 state: the composer replaced the placeholder; open public ingress -14514b0 web: the composer, served behind the existing proxy chain -e921cac design record: every build emits one -d2827c2 design record: what a model was made from, sufficient to regenerate it -70787ea stock: records delegates to the descriptor, and the descriptor stops gating -f5651d3 stock: name the COTS descriptor; the strap becomes the first entry -6836ece tests: close F-034; bound the derived trio at 8 ULP of the oracle record -52d00b5 docs: HANDOFF header commit line moved to b255ebb -b255ebb docs: F-034 rewritten from measurement; handoff updated -114189c docs: PRECISION.md -- scope, guarantees and limits, for lay readers -7b3182c port: the 3x and 4x profile catalogues; build() now exists -af196a2 docs: one canonical handoff, rewritten in place; F-035 -009fcce docs: handoff for the 19 AUG session -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 -6967eef Conformance updates. -c7e32d8 Seed repository: rev-8.0.0 reference, frozen oracle, toolchain, test harness -``` +**Removed.** `git log --oneline` reports it, and the transcribed copy kept here +was ten commits behind within two days of being written — it ended at `a8081e1` +while the composer, the design record author field, STL export and the export +route had all landed above it. + +Nothing derivable from the repository is kept in prose. `PROCESS.md` §10 states +the same rule for itself, and §3 above applies it to the commit hash and the +test count. diff --git a/docs/PROCESS.md b/docs/PROCESS.md index 00f7f5d..6e054bb 100644 --- a/docs/PROCESS.md +++ b/docs/PROCESS.md @@ -230,8 +230,15 @@ a transcription error is silent. `FAILURES.md` is 52 kB of correct prose whose value depends on never being rewritten, and the same hazard applies to any document large enough that nobody will diff it carefully. -This is the `HANDOFF.md` problem one level down: a document **replaced** rather -than **amended** loses content, and nothing reports what left. +The hazard is structural rather than observed: a document **replaced** rather +than **amended** has no diff, so nothing reports what left. + +`HANDOFF.md` is rewritten in place every session, and on 13 SEP it was checked +against both archived handoffs to see what that had cost. It had cost nothing — +the dihedral gap, the three artifact classes, the cross-project mail question +and the toolchain probe recipe were all still there. The practice survived +because a careful author carried the content forward by hand, every time. That +is a property of the authors, not of the method, and it is not one to rely on. ---