From 56e0570f109a8d6e3e73b1879007225f9a5b13d7 Mon Sep 17 00:00:00 2001 From: TheRON Date: Sat, 12 Sep 2026 10:07:04 -0500 Subject: [PATCH] roadmap: two principles, and the contradictions reading it turned up ROADMAP.md was described as a reference rather than a commitment -- something that documents intent and will eventually become a roadmap. The header now says so, and says that HANDOFF section 4 holds the actual order. Sections 1, 2, 3 and 7 are durable and still correct; section 4's sequence and section 5's production assumptions have drifted since 18 AUG. Principle 17: nothing approximate may write to anything reproducible. Principle 4 governs what is hashed; this governs what may reach the thing being hashed. A search index, a documentation system or a language model may read design records freely and may suggest anything to a person, but none may originate a parameter that lands in a record. The failure is silent and compounding -- if suggestions become records and records become the corpus, the corpus teaches itself its own guesses, and every record remains perfectly correct about what it was built from. Where a suggestion informed a build, the record's note field says so, being already excluded from both hashes. No new field is needed and the discipline is written down before there is anything to guard against. Principle 18: a contribution is admitted by the oracle, not parsed by the compiler. Author in whatever notation suits you, freeze the cases inside the pinned toolchain, port, and admit when the oracle passes byte-identically. This has happened twice, with both .scad generators -- it describes what was done rather than what is planned. Two consequences: no second geometry engine is ever kept in step with the first, and legacy/ holds the reference tier rather than superseded code. When someone asks for another input format, the answer is that notation never runs in production. A third principle was drafted and dropped -- that artifacts cross a service boundary and geometry does not. Section 4a's own rule is that use cases precede interface proliferation, and writing a principle about a kernel service boundary while the kernel is not a service is precisely that. It is a gate, not a principle, and the kernel can acquire one when it acquires a boundary. HANDOFF section 11 gains rows 12 through 16, all found by reading ROADMAP.md properly rather than grepping it. Section 5 names a production FQDN that the printed name contradicts. Section 5 says the production proxy is not on the WireGuard side, for a reason the DNAT at 1fdb115 removed. Section 4a says no use case crosses the Kane Fabric boundary and that neither project defines the interface -- membership-gated export is that use case, and IDENTITY-CONTRACT.md defines the identity half, while the siting interface 4a is actually about remains undefined and should stay so. ROADMAP section 4 and HANDOFF section 4 are different lists. And legacy/ is misnamed. None are resolved here. Two are CIVICVS's, two want the whole repository in view at once, one is cosmetic. Recorded so the reconciliation pass finds them written down rather than rediscovering them cold. --- docs/HANDOFF.md | 5 +++++ docs/ROADMAP.md | 31 ++++++++++++++++++++++++++++++- 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index ad9de33..6550303 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -682,6 +682,11 @@ held to it. When in doubt, narrow. | 9 | The composer has no acceptance criteria of its own — only the path to it does | Architect | | 10 | The service is world-reachable and unauthenticated | CIVICVS; §4 item 5 makes this due rather than hypothetical now that it is published | | 11 | Should `ct-baseline.sh` check the ownership of a service's working tree? | CIVICVS — host property, raised by F-037 | +| 12 | `ROADMAP.md` §5 names the production FQDN `mechanical-compiler.manufacturing.kane-il.us`. `dev.mechcomp.kane-il.us` is production and is on printed material | CIVICVS — naming | +| 13 | `ROADMAP.md` §5 says the production proxy is **not** on the WireGuard side, because the NAT was outbound-only. The DNAT at `1fdb115` resolved that, and public TLS now terminates on `wg-pk` | Architect — reconcile | +| 14 | `ROADMAP.md` §4a says no use case crosses the Kane Fabric boundary and that neither project defines the interface, deliberately. Membership-gated export is that use case, and `IDENTITY-CONTRACT.md` defines the identity half. The *siting* interface §4a is about remains undefined and should stay so | Architect — reconcile | +| 15 | `ROADMAP.md` §4 and this document's §4 are different lists. STL export appears only here; `ROADMAP.md` §3 orders dihedral ahead of the bore and neither §4 records it | CIVICVS — priority | +| 16 | `legacy/` holds the reference tier, not superseded code — the name invites a successor to treat it as dead | Architect — cosmetic | 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 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 5dd53b6..cdd700d 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,6 +1,16 @@ # ROADMAP.md -What the Mechanical Compiler is for, and the order in which it gets built. +What the Mechanical Compiler is for. + +**This document records intent, not commitment.** It is a reference for what the +project aims at and why; it does not schedule work and nothing here is a promise +that something will be built. `HANDOFF.md` §4 holds the actual order. Where the +two disagree, §4 wins on sequence and this document wins on purpose. + +§§1, 2, 3 and 7 are the durable parts and are still correct. §4's sequence and +§5's production assumptions have both drifted since 18 AUG; the divergences are +recorded as open questions in `HANDOFF.md` §11 rather than patched here, because +resolving them needs the whole repository in view at once. | | | |---|---| @@ -298,3 +308,22 @@ on whether it makes distributed manufacturing capacity legible. 16. **Conformance precedes backup.** Backing up an unverified configuration preserves the confusion along with the data, and a restore returns it faithfully. +17. **Nothing approximate may write to anything reproducible.** Principle 4 + governs what is hashed; this governs what may reach the thing being hashed. + A search index, a documentation system or a language model may read design + records freely and may suggest anything to a person. None of them may + originate a parameter that lands in a record. The failure is silent and + compounding: if suggestions become records and records become the corpus, + the corpus teaches itself its own guesses, and every record is still + perfectly correct about what it was built from. A suggestion is an input to + a person, never an input to a build — and where one informed a build, the + record's `note` field says so, being already excluded from both hashes. +18. **A contribution is admitted by the oracle, not parsed by the compiler.** + The path from a new profile to the catalogue runs: author it in whatever + notation suits you, freeze its cases inside the pinned toolchain, port it, + and admit it when the oracle passes byte-identically. This has happened + twice, with both `.scad` generators. The consequence is that no second + geometry engine is ever kept in step with the first, and `legacy/` holds the + reference tier rather than superseded code. When someone asks for another + input format, the answer is that notation never runs in production — only + the kernel does.