The dependency rule: Rust, QEMU, and declared C or C++ tools ToyOS can one day build and run; removing machinery updates every prompt that names it

.claude/agents/implementer.md

@@ -55,7 +55,8 @@ Fork sources live outside this repository: a search for callers must also cover
 ## Commits and the pull request
 
 `git commit -F <file>`, never `-m`. No `--amend`, no rebase, no force: merge `origin/main`, never
-rebase onto it. Never touch `toyos-abi/src`, `toyos/src` or `userland/libc/src` unless the brief is
+rebase onto it. Never run `git submodule` in a linked worktree: it writes `core.worktree` into the
+fork's shared config and breaks git in the primary checkout's `rust/`. Never touch `toyos-abi/src`, `toyos/src` or `userland/libc/src` unless the brief is
 an ABI brief. No new dependency.
 
 Push from your branch, never `main`, with `git status --porcelain` empty: `git push -u origin

.claude/agents/orchestrator.md

@@ -53,8 +53,10 @@ settles it and decide.
 
 Glance before every merge: the title and body as `main`'s record, the diff's size against the
 brief's fence, tests added or deleted, CI. Then `gh pr ready` and `gh pr merge --auto --merge`.
-After a landing, sync the primary checkout. A red that is not about the diff is fixed at its
-owner, never re-run away, and nothing but a defect may turn `main` red.
+After a landing, sync the primary checkout. When a landing changes how agents work, every running
+agent is told the new way in one line and merges main before its next round.
+A red that is not about the diff is fixed at its owner, never re-run away, and nothing but a defect
+may turn `main` red.
 A fix for a red lands ahead of feature work. A nightly name red three nights running gets an owner
 issue that day, and is deleted if nobody owns it a week later.
 

.claude/agents/reviewer.md

@@ -50,11 +50,19 @@ above; otherwise it is a NOTE.
   `arch::aarch64` in no generic kernel code; and none of them in a crate whose manifest
   `description` says pure.
   A `4096` in the kernel that means a page is a private copy of `mm::PAGE_SIZE`.
-- **Arrivals.** A binary outside Rust's toolchain, git, QEMU and this repository's own Rust is
-  refused, whether the host starts it — `Command::new`, `libc::system`, an `exec` or
-  `posix_spawn`, a tool a build script or `cc::Build` drives — or `.github/` installs it, by
-  whatever manager or `sh -c`. The ones that stand are those
-  `issues/build/python-and-cc-are-declared.md` declares.
+- **Instructions.** A change that removes or renames a command, flag or step an agent runs updates
+  every prompt that names it — each `CLAUDE.md` and `.claude/agents/*.md` — in the same diff,
+  saying what to do instead. Such an instruction is not the prose "Prose is removed, never
+  reviewed" governs, and `CLAUDE.md`'s "Stale or false prose is deleted", "an agent edits one
+  only when briefed to" and "a `CLAUDE.md` never grows" do not bar the implementer updating it:
+  one left naming what is gone is a BLOCKER.
+- **Arrivals.** A host tool outside Rust and QEMU arrives by `Command::new`, `libc::system`,
+  `exec`, `posix_spawn`, a build script or `cc::Build`, a `.github/` `run:` step or package
+  manager, or `sh -c`, and is declared in
+  `issues/build/the-build-runs-host-tools-outside-rust-and-qemu.md` and nowhere else. A BLOCKER
+  each: an undeclared host tool; one, like Go's `gh`, not built from C or C++ source ToyOS can
+  one day build and run; a binary for one host OS alone; a C or C++ tool taken where a Rust tool
+  does the job; new Python, Perl or shell of ToyOS's own.
   A third-party action `main` does not use is refused, and every `uses:` pins a 40-hex commit
   with its tag in a trailing comment or names a local path that resolves.
   A file added to or deleted from `tests/testcases/tinycc/` moves the count

.github/workflows/nightly.yml

@@ -176,9 +176,8 @@ jobs:
           key: guest-${{ github.run_id }}
       - *serial
 
-  # "Only Rust and QEMU", run rather than argued: `cargo run -- --build-only`
-  # from a fresh machine. `sid` as it stands, image and archive both, and no
-  # cache — a fresh machine is the premise.
+  # `cargo run -- --build-only` from a fresh machine. `sid` as it stands,
+  # image and archive both, and no cache — a fresh machine is the premise.
   portability-linux:
     runs-on: ubuntu-24.04
     timeout-minutes: 350

CLAUDE.md

@@ -58,11 +58,11 @@ A subdirectory `CLAUDE.md` loads when a file in that subtree is `Read`, and not
 
 ## Dependencies
 
-Only **Rust** and **QEMU** (for development), on any host OS and architecture — the development machine is nothing special. The rules: no binary outside those two — a macOS binary is a hard no, and "only for tests" does not soften it; only general and widely used crates — one that does *our* job we write ourselves, and a driver crate never; no Python; third-party crates are used as published, and a fork carries a change written to upstream quality and goes when upstream has it. No upstream pull requests are sent for now: ToyOS needs more attention and more contributors before upstream projects take it seriously, and upstreams tend to refuse AI-first projects and their contributions. A third-party source ToyOS cannot build without changing it is carried as an unmodified-source packaging mirror with a byte-identity gate, not as a fork. The north star is **self-hosting**: nothing — build, test, or verification — rests on a host binary. Ask of anything new: could this ever run inside ToyOS? Self-hosting means ToyOS rebuilds itself on ToyOS and reproduces the host's bytes; a bootstrap from source with no binary seed is out of scope.
+**Rust** and **QEMU** for development, on any host OS and architecture — the development machine is nothing special. Beside them, where no Rust tool does the job, only C or C++ tools ToyOS can one day build and run (Python, Perl, CMake, Ninja, make), each declared. No binary for one host OS alone: a macOS binary is a hard no, and "only for tests" does not soften it. ToyOS's own code is Rust; it writes no Python, Perl or shell of its own. Only general and widely used crates — one that does *our* job we write ourselves, and a driver crate never; third-party crates are used as published, and a fork carries a change written to upstream quality and goes when upstream has it. No upstream pull requests are sent for now: ToyOS needs more attention and more contributors before upstream projects take it seriously, and upstreams tend to refuse AI-first projects and their contributions. A third-party source ToyOS cannot build without changing it is carried as an unmodified-source packaging mirror with a byte-identity gate, not as a fork. The north star is **self-hosting**: nothing — build, test, or verification — rests on a host binary. Ask of anything new: could this ever run inside ToyOS? Self-hosting means ToyOS rebuilds itself on ToyOS and reproduces the host's bytes; a bootstrap from source with no binary seed is out of scope.
 
 Vendor firmware a device verifies by its maker's signature may be shipped: pinned by version and hash, redistributable unmodified, recorded in `NOTICE`, and loaded only by that device's own driver through its IOMMU domain; it never executes on the CPU.
 
-The bar is not yet the tree. The standing failures are declared rather than removed — Python via `rust/x`, `cc` for every host link, two macOS FAT tools. `NOTICE` names every committed third-party file with its hash, upstream and licence; an image carrying `DOOM1.WAD` may not be sold.
+The bar is not yet the tree: `.claude/agents/reviewer.md`, "Arrivals", says where every host tool and every standing failure is declared. `NOTICE` names every committed third-party file with its hash, upstream and licence; an image carrying `DOOM1.WAD` may not be sold.
 
 - **toyos-ld** — frozen: everything links with rust-lld, and toyos-ld stays only as the linker inside ToyOS until lld runs there, then goes.
 - **rust/** — Rust compiler/std fork with ToyOS platform support (submodule). Auto-bootstraps; kept current with upstream. Its rules: `.claude/agents/implementer.md`, "A fork".

README.md

@@ -10,7 +10,7 @@ cargo run
 ```
 
 One command, and a complete OS boots. No Make, no Docker, no LLVM to install,
-no cross-toolchain to assemble, no system linker. Everything that boots is
+no cross-toolchain to assemble. Everything that boots is
 built by a toolchain in this repository.
 
 Rust and QEMU, plus the four things `rustc`'s own bootstrap needs on every
@@ -225,8 +225,7 @@ same font the kernel blits.
 - A C compiler on `PATH` as `cc`, and a Python 3
 - CMake and Ninja
 
-The last two lines are `rustc`'s and not ToyOS's, and nothing that boots touches
-them. `rustc` links every **host** binary through `cc`, which rustup does not
+`rustc` links every **host** binary through `cc`, which rustup does not
 install. `rust/x`, the entry point to rustc's own bootstrap, is a shell script
 whose whole job is to find a Python to run `bootstrap.py` with — so a clean
 clone needs one, and so does every toolchain change. And that bootstrap builds