Merge pull request 'Architecture: the toolchain step (D3), and only looking before the go-ahead (D1)' (#135) from toolchain-step-arch into main

Reviewed-on: #135
Reviewed-by: Don Garrett <dgarrett@acm.org>

docs/Architecture.md

@@ -591,6 +591,10 @@ mean, how it fits, its first step. Labels steer what happens next:
 | `discuss` | Talks it through before anything |
 | `design` | Agrees the design (D2) before any code |
 
+- **Until the go-ahead it only looks:** reading and checking (versions,
+  builds, tests) run; anything that changes something is refused by the fast
+  path (P4). What the work will need, a toolchain change included, goes in the
+  restatement, so the go-ahead covers it.
 - **It also talks first** when it finds the report unclear (it asks instead of
   restating) or can't reproduce a bug. It never fixes a bug it couldn't see.
 - **It never classifies an issue itself;** it may suggest a label. A missing label
@@ -672,15 +676,32 @@ at the latest default branch, and **set aside**, never silently discard, anythin
 left over (uncommitted changes, local branches, unpushed commits), reporting it.
 Build artifacts and caches in the workspace never survive into a new task.
 
-**Toolchain preflight:** when the workspace is prepared, the agent determines what
+**The toolchain step** makes the build VM and the project's own files agree: a
-the project needs and installs any gap **before any planning**; toolchain versions
+bounded run of the item's driver model that installs what the project needs and
-become facts (L6).
+keeps its pins, setup documentation (the README or wherever the project keeps it)
+and CI configuration in step. **The repository is the record:** reviewed in PRs,
+surviving any VM, and the same instructions a person cloning it would follow. It
+starts two ways:
+- **The harness starts it when the build VM isn't set up for the project** (new,
+  rebuilt or wiped, which the model can't know): before every run it checks the
+  VM's baseline, the workspace clone (cloned again if gone) and a per-project
+  marker that a finished step leaves. This step sets the VM up from the
+  repository and changes nothing in it; files out of step with reality are
+  reported, for the driver to act on.
+- **The driver requests it** when the work needs a toolchain change, once the work
+  is agreed (D1); its edits land in the current milestone, so they are reviewed
+  with the work.
+
+**Versions are facts the harness reads itself** (L6): it runs each tool's version
+command (version commands only), checks them again before later runs and reports a
+change, and a PR says what its work was tested with. **A rebuilt VM's new host
+key** is trusted only on the operator's word.
 
 **The build VM is the agent's to change:** installing packages and toolchains there,
 cleaning caches or reinstalling dependencies to fix a broken build are contained,
-reported but not asked about. Every install is recorded (as a fact and in scope
+reported but not asked about. Changes meant to last go into the repository's files
-memory) so the VM can be rebuilt; recurring ones go into the template (X4).
+through a toolchain step; recurring ones go into the template (X4). Installing on
-Installing on any other host is dangerous.
+any other host is dangerous.
 
 ### D4. Git, branches and PRs
 

docs/Development-Plan.md

@@ -377,7 +377,7 @@ agent merging behind protection it can't satisfy, verified by a test (D4, D5, #6
 
 ### Phase 4 — The environment
 
-**M4.1 Toolchain preflight, M4.2 recording installs, M4.3 environment repair.**
+**M4.1 Toolchain preflight, M4.2 the toolchain step, M4.3 environment repair.**
 *Pre-approved.* All on the build VM (D3).
 
 **M4.1** is **done** (this PR). A model works out and sets up what a project
@@ -402,6 +402,18 @@ needs; code makes sure that happens, bounds it and checks the result.
   without it), preflight runs on the driver's model, gaps don't block. Turning
   off unattended upgrades and the template's baseline are template choices.
 
+**M4.2** *(revised with the operator: in place of recording installs).* The
+preflight becomes **the toolchain step** (D3): make the VM and the project's own
+files agree, with the repository as the record rather than a harness-kept one.
+- Started by the harness when the VM isn't set up for the project (M4.1's
+  checks): it sets the VM up from the repository and edits nothing there.
+- Requested by the driver (`toolchain_step(reason)`) once work is agreed: it
+  installs, then brings pins, setup docs and CI configuration in step; the edits
+  land in the current milestone's PR. Refused before the go-ahead.
+- Run in a transcript of its own; the driver sees only its report.
+- With it, D1's rule made structural: until the go-ahead the fast path refuses
+  anything that isn't harmless, so needs go in the restatement.
+
 ### Phase 5 — Memory
 
 **M5.1 The vault.** *Pre-approved.* The folder, per-agent mounts, control tools,