Handover push
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user