From 3e7e7c934d7ed809cf36e94125f216c95dd4c5db Mon Sep 17 00:00:00 2001 From: TheRON Date: Mon, 17 Aug 2026 12:50:12 -0400 Subject: [PATCH] Added PROCESS.md --- docs/ENVIRONMENT.md | 2 + docs/FAILURES.md | 1 + docs/PROCESS.md | 373 ++++++++++++++++++++++++++++++++++++++++++ docs/ROADMAP.md | 2 +- docs/STAGING-STATE.md | 5 + 5 files changed, 382 insertions(+), 1 deletion(-) create mode 100644 docs/PROCESS.md diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md index 2bf126a..27e5551 100644 --- a/docs/ENVIRONMENT.md +++ b/docs/ENVIRONMENT.md @@ -11,6 +11,7 @@ Specification for a Mechanical Compiler instance. | Instance state | `STAGING-STATE.md`, and later `PRODUCTION-STATE.md` | | Failure evidence | `FAILURES.md` | | Project sequence | `ROADMAP.md` | +| Working method | `PROCESS.md` | --- @@ -24,6 +25,7 @@ disagreed with it. Everything specific to `srv-b` has been removed. ### Authority order +0. **`PROCESS.md`** — how work is done. Read before issuing any command. 1. **The instance state file** — factual, wins on any question of what is true. 2. **`FAILURES.md`** — evidence from contact with hosts. Read this *before* writing automation, not after. diff --git a/docs/FAILURES.md b/docs/FAILURES.md index 63984d2..f206e09 100644 --- a/docs/FAILURES.md +++ b/docs/FAILURES.md @@ -7,6 +7,7 @@ Compiler environment. |---|---| | Scope | All instances. Staging entries are marked `srv-b`. | | Updated | 2026-08-17, after work order 003 | +| Method | `PROCESS.md` section 7 | | Rule | Append only. Never edit an entry except to add a `Resolution` line. | | Numbering | Sequential, never reused. See §0 on the renumbering. | diff --git a/docs/PROCESS.md b/docs/PROCESS.md new file mode 100644 index 0000000..3153047 --- /dev/null +++ b/docs/PROCESS.md @@ -0,0 +1,373 @@ +# PROCESS.md + +How work gets done on the Mechanical Compiler. + +| | | +|---|---| +| Created | 2026-08-17 | +| Scope | All work on a Mechanical Compiler instance | +| Companions | `ENVIRONMENT.md`, `STAGING-STATE.md`, `FAILURES.md`, `ROADMAP.md` | + +--- + +## 0. Why this document exists + +The four companion documents describe what the environment **is**. None of them +describes how work gets **done** in it — where files land, who runs what, how a +change travels from a conversation into a running container. + +Until now that gap was filled by restating the mechanics inside each work +order. That worked while the orders were written consecutively by one author. +It does not survive a handoff: an assistant reading `ENVIRONMENT.md` learns how +the host is built and nothing about how to operate on it. + +**Read this before your first command.** + +--- + +## 1. Who does what + +Three parties, and confusing them is the most common way to waste a session. + +| Party | Has | Does | +|---|---|---| +| **Operator** (CIVICVS) | A shell on `srv-b` and a file manager | Runs every command. Uploads files. Decides. | +| **Assistant** | This conversation | Writes commands, reads output, writes code and documents | +| **Architect** | This conversation, in a different mode | Sets specification, accepts work, maintains the documents | + +### The constraint that shapes everything + +**The operator 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 ability to +`scp`. Every file arrives by upload to a folder on `srv-b`; every command runs +in that one shell. + +An assistant that assumes otherwise produces instructions the operator cannot +execute. This has already happened once. + +### What follows from it + +- Files reach a container as: **upload to `srv-b`** → `pct push` or expand and + copy → `pct exec` to act on them. +- `srv-b` is the only place a human types. Containers are reached through + `pct exec`, never by SSH from elsewhere. +- **This is a legitimate deployment path, not a workaround.** Do not design + around a git client that does not exist. + +--- + +## 2. Two modes of work, and they are not the same + +Applying the wrong one is slow in one direction and dangerous in the other. + +### Infrastructure mode + +For anything that changes the host, the containers, the network, or a service +that other work depends on. + +- One command group at a time +- Read-only before write +- Record a failure **before** correcting it, in `FAILURES.md` format +- Smallest corrective experiment — not the one that also fixes three adjacent + worries +- Preserve a rollback copy before editing any configuration file +- Prove the negative: assert the forbidden path fails, not that the interface + is gone +- Assert health **after a host reboot**, never before + +This is deliberate ceremony. Each step is irreversible or expensive to undo, +and the failure log is a deliverable in its own right — it is the primary input +to the eventual production automation. + +Work orders 001 through 003 were all infrastructure mode. + +### Development mode + +For anything inside the repository: code, tests, documents, fixtures. + +- Iterate freely. Edit, run the tests, edit again. +- No command-group ceremony. A test-fix-rerun loop is not a provisioning step. +- Failures during a normal red-green loop are **not** `FAILURES.md` entries. +- Commit when something works, not when something is finished. + +**The distinction is reversibility.** A wrong `iptables` rule can strand the +operator. A wrong line of Python fails a test and gets deleted. Ceremony +appropriate to the first is obstruction applied to the second. + +### Which mode am I in? + +Ask: *if this is wrong, what does it cost?* + +| Cost | Mode | +|---|---| +| A rebooted host, a lost shell, a broken service | Infrastructure | +| A red test | Development | + +If genuinely unsure, use infrastructure mode. Being slow is recoverable. + +--- + +## 3. Getting files into the environment + +### The path + +``` +assistant produces a tarball + -> operator downloads it + -> operator uploads it to /root/incoming on srv-b (file manager) + -> operator expands it on srv-b + -> pct push, or expand-then-copy, into CT 100 + -> pct exec to act on it +``` + +**REQ** — `/root/incoming` on `srv-b` is the landing area. One directory, +always the same, so nothing has to be remembered between sessions. + +**REQ** — Files landing in a container must end up owned by `mechcomp`. +`pct push` writes as root; fix ownership immediately afterwards. See F-008 — +repository operations run as the service user, and a root-owned file inside the +tree causes exactly that failure later. + +**REQ** — An assistant delivering files states, in this order: what the archive +contains, where it expands, what it overwrites, and how to verify it landed +correctly. "Overwrites nothing" is a claim that must be checked, not assumed. + +### Delivering a whole tree + +Prefer one tarball that expands over the existing tree. Individual file paths +are error-prone to transcribe through a file manager. + +### Delivering a single small file + +For anything that fits comfortably on screen, a heredoc in the `srv-b` shell is +faster than an upload, and leaves the content visible in the session transcript +where it can be checked. + +--- + +## 4. The repository + +**Gitea is the source of truth.** `https://gitea.barternetwork.us/TheRON/mechanical-compiler` + +CT 100 holds a clone at `/var/www/mechcomp`, owned by `mechcomp`. + +### Two directions, both valid + +**Gitea → container.** `git pull` inside CT 100, as `mechcomp`. Use this +whenever the change already exists in Gitea. + +**Upload → container → Gitea.** Land the files, verify they work, then commit +and push from inside CT 100. Use this when the assistant produced something new. + +The second direction is the normal one for assistant-produced work, because the +operator has no git client outside the environment. + +**REQ (F-008)** — Every `git` command runs as `mechcomp`. Never as root, and +never add a root `safe.directory` exception — it would mask every future +instance of the same mistake. + +### What must be true before a push + +- The oracle verifies: `python3 fixtures/strap-beam-8.0.0/make_fixtures.py --verify` +- The test suite runs, with a result the assistant has actually seen +- `git status` shows nothing unexpected — particularly not `venv/` + +### Recording provenance + +Artifacts are attributed to the **commit that produced them**, not to a +timestamp or a file copy. When an artifact is generated, the commit SHA of the +tree that produced it is part of its record. This is why the transport does not +matter but the SHA does. + +--- + +## 5. The development loop + +Inside CT 100, as `mechcomp`, from `/var/www/mechcomp`: + +``` +make deps once, and after any requirements change +make test the loop +make verify-oracle before any commit that touches fixtures +``` + +### The oracle is the gate + +`fixtures/strap-beam-8.0.0/` holds 123 frozen cases. It is the acceptance +criterion for the port, and it is not negotiable. + +**The ten rejected cases are part of the contract.** A port that accepts them is +wrong however good its numbers are elsewhere. Reproducing geometry is +straightforward; keeping the constraint that made the geometry trustworthy is +the actual work. + +**The oracle is never edited to make a test pass.** If the port disagrees with +it, the port is wrong until proven otherwise. If the oracle is genuinely wrong, +that is a finding, it is recorded, and it is regenerated inside the pinned +toolchain — never hand-edited. + +### Test discipline + +**A test must distinguish failure of the tool from failure of the thing under +test** (F-027). Every negative assertion first establishes that it could have +observed the positive case. A test whose failure mode is indistinguishable from +success manufactures confidence. + +Prove a new harness by making it fail deliberately before trusting it green. + +--- + +## 6. Work orders + +A work order is an infrastructure-mode instruction set. Development work does +not need one. + +### When to write one + +- The work changes the host, containers, network, or a shared service +- The work has an acceptance criterion that can be stated in advance +- The work will be executed by someone other than the author + +### Required sections + +| Section | Purpose | +|---|---| +| Scope | In and out. Explicit "do not touch" list. | +| Success criteria | Strict, testable, stated before the work | +| Known state | So the operator does not re-derive what is already recorded | +| Command groups | One at a time, read-only first | +| Acceptance | What must be true to close | +| Reporting | What comes back to the architect | + +### Executing one + +- One group at a time. Paste output back before the next. +- Record a failure before correcting it. +- **A defect in the work order is a finding**, not something to work around + silently. F-024 and F-028 are work-order defects, logged as such. +- "The problem is elsewhere and here is the evidence" is a complete outcome. + Do not manufacture a local workaround for a remote problem. + +--- + +## 7. When something goes wrong + +### Is it a `FAILURES.md` entry? + +**Yes** if it is a surprise about the environment: something behaved +differently from what the specification or a work order said, and a future +automation writer would get it wrong the same way. + +**No** if it is an ordinary development failure: a red test, a syntax error, a +wrong algorithm. Those are the loop working. + +### Entry format + +``` +### F-nnn — one-line summary +Host or container. Phase. +**Observed:** verbatim where possible +**Cause:** proven, or explicitly "unproven" +**Correction:** the smallest change that fixed it +**Consequence:** what the specification or automation must do differently +``` + +An entry with no `Consequence` is either not understood or not worth recording. + +**"Unproven" is a respectable result.** F-006, F-012 and F-022 are carried open +and the log is better for it. Never invent a cause to close an entry, and never +close one on a change that merely coincided with the symptom disappearing. + +### Escalating + +Stop and ask the operator when: + +- A decision is needed that is not the assistant's to make +- The work requires changing infrastructure outside this project +- A **REQ** in the specification cannot be satisfied +- The specification and observed reality disagree + +The last one is not a blocker — reality wins, and the specification is +corrected. But it is always worth saying out loud. + +--- + +## 8. Session handoff + +Sessions end abruptly. Assume the next assistant has these documents and +nothing else. + +### Before a session ends + +- Anything working is committed and pushed +- Anything learned is in `FAILURES.md` +- Anything changed on a host is in `STAGING-STATE.md` +- Any open decision is in `STAGING-STATE.md` section 6 + +### Starting a session + +Read in this order: + +1. **`PROCESS.md`** — this document +2. **`STAGING-STATE.md`** — what is true right now +3. **`FAILURES.md`** — what has already gone wrong +4. **`ENVIRONMENT.md`** — the specification +5. `ROADMAP.md` — where it is going + +If 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 + +1. `STAGING-STATE.md` — factual, wins on what is true +2. `FAILURES.md` — evidence from contact with real hosts +3. `ENVIRONMENT.md` — the specification, corrected when proven wrong +4. `ROADMAP.md` — sequence + +**A permanent deviation is not a deviation. It is the specification.** Promote +it and delete the exception. + +--- + +## 9. Instructions the operator can actually run + +This section exists because it has already gone wrong. + +**REQ** — One command group per message. Wait for output. + +**REQ** — Commands run in the `srv-b` shell, or via `pct exec` from it. Nothing +assumes a tool the operator does not have. + +**REQ** — A group is copy-pasteable as a block, with `echo` markers separating +sections so the output can be read back. + +**REQ** — State what the expected output is. An operator who cannot tell +success from failure cannot report usefully. + +**Do not** deliver a numbered multi-stage procedure spanning several systems and +expect it to be executed. It will not be, and the parts that are will not be +separable in the output. + +**Do not** assume the operator will improvise the missing step. If a command +needs a directory to exist, create it in the same group. + +--- + +## 10. Current mode + +**Infrastructure: complete and accepted.** Host, containers, network isolation, +bastion access, TLS, reverse proxy, mail alerting, disk monitoring. See +`STAGING-STATE.md`. + +**Backup: deliberately postponed.** Nothing exists yet whose loss would cost +more than an afternoon; the documents are in Gitea. This changes when +`artifacts/` stops being empty. + +**Development: starting.** First work item is the Shapely port — +`pytest -n auto` green against the 123 frozen cases. + +From here the mode is **development** unless the work touches the host, the +containers, or a shared service. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index e0eccd1..e102bd4 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -5,7 +5,7 @@ What the Mechanical Compiler is for, and the order in which it gets built. | | | |---|---| | Updated | 2026-08-17 | -| Companions | `ENVIRONMENT.md`, `STAGING-STATE.md`, `FAILURES.md` | +| Companions | `PROCESS.md`, `ENVIRONMENT.md`, `STAGING-STATE.md`, `FAILURES.md` | --- diff --git a/docs/STAGING-STATE.md b/docs/STAGING-STATE.md index 321cb0b..a962226 100644 --- a/docs/STAGING-STATE.md +++ b/docs/STAGING-STATE.md @@ -8,6 +8,7 @@ Live state of the Mechanical Compiler staging instance on `srv-b`. | Instance | Staging / development | | Specification | `ENVIRONMENT.md` revision 5 | | Failure log | `FAILURES.md` | +| Process | `PROCESS.md` — **read first** | | Method | Manual, one command group at a time | --- @@ -21,6 +22,10 @@ defective and must be corrected. Completed and remaining work are in the same document deliberately. They are two halves of one boundary; separating them guarantees they drift. +**Read `PROCESS.md` before your first command.** It describes how work is done +here — who runs what, on which machine, with which tools. This file describes +only what is currently true. + Before any command: read this file, confirm the immediately relevant live state with a read-only command, then issue one command group. If it fails, record it in `FAILURES.md` before changing anything else.