Architecture: the toolchain step (D3), and only looking before the go-ahead (D1) #135

2026-10-08T17:18:30Z

dev-agent commented

2026-10-08 17:18:30 +00:00

The architecture changes for M4.2, the toolchain step, as discussed. This PR is docs only; the implementation follows in its own PR.

D3: the preflight and the install recording become the toolchain step.

What it is: a bounded run of the item's driver model that makes the build VM and the project's own files agree. It installs what the project needs, and keeps its pins, setup docs (the README, or wherever the project keeps them) and CI configuration in step.
The record: the repository. It's reviewed in PRs, survives any VM, and holds the same instructions a person cloning it would follow.
Started by the harness when the VM isn't set up for the project: new, rebuilt or wiped. The checks are M4.1's: baseline, clone and marker. In this mode it sets the VM up from the repository and edits nothing there, and reports files that are out of step.
Requested by the driver once work is agreed. Its edits land in the current milestone, so they're reviewed with the work.
Unchanged from M4.1: versions are facts the harness reads itself, drift is reported, PRs say what the work was tested with, and a new host key is trusted only on the operator's word.
"Every install is recorded… in scope memory" is replaced by: changes meant to last go into the repository's files through a toolchain step.

D1: until the go-ahead, the agent only looks. Reading and checking run; anything that changes something is refused by the fast path. What the work needs, a toolchain change included, goes in the restatement. This closes a gap in today's code: before the go-ahead, run_command is offered for looking around, and an install would have run.

Development Plan: M4.2 becomes the toolchain step, in place of recording installs, with the points above.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

The architecture changes for **M4.2, the toolchain step**, as discussed. This PR is docs only; the implementation follows in its own PR. **D3:** the preflight and the install recording become **the toolchain step**. - **What it is:** a bounded run of the item's driver model that makes the build VM and the project's own files agree. It installs what the project needs, and keeps its pins, setup docs (the README, or wherever the project keeps them) and CI configuration in step. - **The record:** the repository. It's reviewed in PRs, survives any VM, and holds the same instructions a person cloning it would follow. - **Started by the harness** when the VM isn't set up for the project: new, rebuilt or wiped. The checks are M4.1's: baseline, clone and marker. In this mode it **sets the VM up from the repository and edits nothing there**, and reports files that are out of step. - **Requested by the driver** once work is agreed. Its edits land in the current milestone, so they're reviewed with the work. - **Unchanged from M4.1:** versions are facts the harness reads itself, drift is reported, PRs say what the work was tested with, and a new host key is trusted only on the operator's word. - **"Every install is recorded… in scope memory" is replaced** by: changes meant to last go into the repository's files through a toolchain step. **D1:** *until the go-ahead, the agent only looks.* Reading and checking run; anything that changes something is refused by the fast path. What the work needs, a toolchain change included, goes in the restatement. This closes a gap in today's code: before the go-ahead, `run_command` is offered for looking around, and an install would have run. **Development Plan:** M4.2 becomes *the toolchain step*, in place of *recording installs*, with the points above. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

dev-agent added 1 commit 2026-10-08 17:18:30 +00:00

Architecture: the toolchain step (D3), and only looking before the go-ahead (D1)

CI / checks (push) Skipped

CI / checks (pull_request) Successful in 1m54s

Details

CI / e2e (pull_request) Successful in 4m1s

Details

66c8ded409

D3's preflight and install recording become the toolchain step: a
bounded run of the item's driver model that makes the build VM and the
project's own files (pins, setup docs, CI configuration) agree, with
the repository as the record. The harness starts it when the VM isn't
set up for the project (and then it edits nothing in the repository);
the driver requests it once work is agreed, and its edits land in the
current milestone. Versions stay facts the harness reads itself; a
rebuilt VM's new host key is trusted only on the operator's word.

D1 gains the rule that until the go-ahead the agent only looks:
anything that changes something is refused by the fast path, so what
the work needs goes in the restatement.

The Development Plan's M4.2 follows: the toolchain step, in place of
recording installs.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

dongar approved these changes

2026-10-08 17:28:52 +00:00

dongar merged commit 97ea451629 into main

2026-10-08 17:28:56 +00:00

dongar deleted branch toolchain-step-arch

2026-10-08 17:28:56 +00:00

dev-agent referenced this pull request

2026-10-08 17:37:21 +00:00

M4.2: the toolchain step #136

dev-agent referenced this issue from a commit

2026-10-08 17:37:21 +00:00

M4.2: the toolchain step