Crafter.Build/.review-gates/lenses/repo-bug-prover.md

## This repository: Crafter.Build

The execution contexts to enumerate, beside the charter's:
- `project.cpp` is compiled to a shared object and loaded into the running
  crafter-build, resolving `Crafter::` symbols from the executable
  (`--export-dynamic`); its static initialisers run at load. Its sibling
  projects (`GitProject`, `LocalProject`) load the same way into the same
  process, and its `#pragma crafter dependency` targets are built for the
  host first, on every load.
- The clang++, clang and llvm-ar the tool spawns, and the git and cmake it
  runs, are shell commands (`popen`, `std::system` in `:Platform`), many in
  parallel; such a step fails on its exit code, never because it printed.
  Running a test or a built artifact is a shell command too (`:Test`,
  `:Clang`). A path, file name or flag that reaches one with a space or a
  shell metacharacter in it is an input to attack. Other steps run inside
  the process, among them glslang's shader compiles, on a thread of their
  own per stale shader (`:Shader`), and lint's parse through the libclang
  the linter dlopens (`:Lint`).
- Several crafter-build processes share `~/.cache/crafter.build/` at once:
  the std and Crafter.Build PCMs per target and march (the
  `ConcurrentCacheRace` test), and the external clones with their `.lock`
  files.
- Three builds of the tool: the bootstrap from `build.sh` (without
  `CRAFTER_BUILD_HAS_ASSET`), the self-hosted binary on the host's LLVM, and
  the Flatpak on its own LLVM under `/app`, in a sandbox whose `/usr` is the
  Freedesktop SDK's. Their toolchains can be a release apart.
- Targets: the host triple, a sysroot (aarch64, musl), `x86_64-w64-mingw32`
  under wine, `wasm32-wasi*` under wasmtime (or wasmer for `-r`), and
  browser builds through the runtime in `wasi-runtime/`.
- Incremental builds: a first build, a rebuild after an edit, a rebuild
  after a toolchain or flag change and a build after `clean` start from
  different states; whatever changes what gets compiled has to reach
  `VariantId()`, or a stale artifact is reused.
- Tests: each its own subprocess, in parallel, with a 60 s timeout. A test
  that edits or touches files stages a copy under
  `fs::temp_directory_path()`; one that only builds its fixture builds it in
  place, into the fixture's own `bin/` and `build/` in the checkout.

Semantics to read on disk rather than recall: libc++ and clang as the host
installs them (`/run/host/usr/include/c++/v1`,
`/run/host/usr/share/libc++/v1/std.cppm`,
`/run/host/usr/lib/clang/<major>/include`), the dependencies as cloned
(`~/.cache/crafter.build/external/<Name>-<hash>/`), the vendored
`lib/DirStackFileIncluder.h`. The Flatpak's own LLVM is not readable from
here: a semantic that may differ between LLVM releases is unverified for
the Flatpak build.
feat(review): set up Crafter.Review's pre-push review Crafter.Review reviews a frozen commit range before it is pushed: the approach, a static proof of the code's bugs, and every claim in the messages and in the documentation the range changes, one claude process per lens and unit, or per whole-range pass, and the owner approves the exact frozen hash before the push. This sets it up for this repository. .review-gates/config.json turns on three lenses in the commits mode, at xhigh: repo-better-solution, repo-bug-prover and repo-facts. The functional lens is off: it exercises a web application through a browser, and this repository's product is a command-line tool. The security lens is off by the owner's ruling: crafter-build stores no secret of its own, and while its Flatpak runs with the user's SSH agent (--socket=ssh-auth) and the whole host filesystem (--filesystem=host), everything it runs is code its user chose to run. The rules CI keeps around its token and signing key go to the approach lens's section instead. gate0 lists the commands run by hand before a freeze. build.sh comes first, because bin/crafter-build compiles project.cpp against the interfaces it was bootstrapped with, and lint comes after the self-host build, because lint's AST rules parse with the module PCMs a build leaves and lint builds only the std PCM itself. .review-gates/lenses/ holds this repository's section of each lens's charter, appended to the text Crafter.Review ships: that AGENTS.md is absent from the frozen tree, the layers and the consumers of interfaces/, the execution contexts a bug can hide in, where libc++ and clang are readable from the review's sandbox, and what a "passes the suite" claim traces to. The /prepush skill that crafter-review init writes stays untracked. It is generated from the installed Crafter.Review and refreshed by every init, so a committed copy would lag the binary it describes. One init per checkout restores it, which AGENTS.template.md now says, together with the rules freeze holds every commit of a range to: signed (requireSigned), with the owner's address as its author and committer (authors), and no AI attribution trailer (aiTrailers forbid). 2026-11-01 02:55:03 +01:00			`## This repository: Crafter.Build`

			`The execution contexts to enumerate, beside the charter's:`
			- `project.cpp` is compiled to a shared object and loaded into the running
			crafter-build, resolving `Crafter::` symbols from the executable
			(`--export-dynamic`); its static initialisers run at load. Its sibling
			projects (`GitProject`, `LocalProject`) load the same way into the same
			process, and its `#pragma crafter dependency` targets are built for the
			`host first, on every load.`
			`- The clang++, clang and llvm-ar the tool spawns, and the git and cmake it`
			runs, are shell commands (`popen`, `std::system` in `:Platform`), many in
			`parallel; such a step fails on its exit code, never because it printed.`
			Running a test or a built artifact is a shell command too (`:Test`,
			`:Clang`). A path, file name or flag that reaches one with a space or a
			`shell metacharacter in it is an input to attack. Other steps run inside`
			`the process, among them glslang's shader compiles, on a thread of their`
			own per stale shader (`:Shader`), and lint's parse through the libclang
			the linter dlopens (`:Lint`).
			- Several crafter-build processes share `~/.cache/crafter.build/` at once:
			`the std and Crafter.Build PCMs per target and march (the`
			`ConcurrentCacheRace` test), and the external clones with their `.lock`
			`files.`
			- Three builds of the tool: the bootstrap from `build.sh` (without
			`CRAFTER_BUILD_HAS_ASSET`), the self-hosted binary on the host's LLVM, and
			the Flatpak on its own LLVM under `/app`, in a sandbox whose `/usr` is the
			`Freedesktop SDK's. Their toolchains can be a release apart.`
			- Targets: the host triple, a sysroot (aarch64, musl), `x86_64-w64-mingw32`
			under wine, `wasm32-wasi*` under wasmtime (or wasmer for `-r`), and
			browser builds through the runtime in `wasi-runtime/`.
			`- Incremental builds: a first build, a rebuild after an edit, a rebuild`
			after a toolchain or flag change and a build after `clean` start from
			`different states; whatever changes what gets compiled has to reach`
			`VariantId()`, or a stale artifact is reused.
			`- Tests: each its own subprocess, in parallel, with a 60 s timeout. A test`
			`that edits or touches files stages a copy under`
			`fs::temp_directory_path()`; one that only builds its fixture builds it in
			place, into the fixture's own `bin/` and `build/` in the checkout.

			`Semantics to read on disk rather than recall: libc++ and clang as the host`
			installs them (`/run/host/usr/include/c++/v1`,
			`/run/host/usr/share/libc++/v1/std.cppm`,
			`/run/host/usr/lib/clang/<major>/include`), the dependencies as cloned
			(`~/.cache/crafter.build/external/<Name>-<hash>/`), the vendored
			`lib/DirStackFileIncluder.h`. The Flatpak's own LLVM is not readable from
			`here: a semantic that may differ between LLVM releases is unverified for`
			`the Flatpak build.`