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
|
|
|
|
|
|
|
|
|
|
A C++26 modules build system that builds itself. The stated design is
|
|
|
|
|
`README.md` (the manual) and `AGENTS.template.md` (the contributor guide;
|
|
|
|
|
`AGENTS.md` is written from it by a crafter-build build or test run, not
|
|
|
|
|
by `build.sh`, and is not in the tree).
|
|
|
|
|
Its "Design rules" and "Security considerations" are the owner's
|
|
|
|
|
decisions: a range that departs from one without saying so is a finding;
|
|
|
|
|
whether one should change is the owner's call, not a defect of the range.
|
|
|
|
|
Among them, for CI, which holds the workflow's token and the signing key
|
|
|
|
|
its runner mounts: no secret is added to the workflow, and the
|
|
|
|
|
environment is never echoed in it.
|
|
|
|
|
|
|
|
|
|
The layers: the library (`interfaces/`, `implementations/`), which the
|
|
|
|
|
executable wraps and every `project.cpp` is compiled against; this
|
|
|
|
|
repository's own `project.cpp`; `build.sh`, the bootstrap that builds the
|
|
|
|
|
tool without the tool; the Flatpak (`packaging/flatpak/`), which bundles
|
|
|
|
|
the LLVM users build with; CI (`.forgejo/workflows/ci.yaml`). A target
|
|
|
|
|
difference branches on `cfg.target` at run time, never on the host; an
|
|
|
|
|
output path goes through `BinDir()`, `BuildDir()` or `PcmDir()`; whatever
|
|
|
|
|
changes what gets compiled or bundled reaches `VariantId()`.
|
|
|
|
|
|
|
|
|
|
Search first: the partitions' own helpers (`RunBuildCommand`,
|
|
|
|
|
`RunCommandChecked`, `Progress::Diagnostic`, `ApplyStandardArgs`,
|
|
|
|
|
`HostTarget`, `GitProject`, `LocalProject`); the Crafter.* libraries the
|
|
|
|
|
tree already uses, cloned under `~/.cache/crafter.build/external/`; libc++
|
|
|
|
|
and clang as the host installs them (`/run/host/usr/include/c++/v1`,
|
|
|
|
|
`/run/host/usr/lib/clang/`); git, cmake and flatpak-builder.
|
|
|
|
|
|
|
|
|
|
Commit shape here: a fix, its test and its README change are separate
|
|
|
|
|
commits when each stands on its own, in that order, and a bug fix ships
|
|
|
|
|
with a test that fails before it. That split is not a later commit
|
|
|
|
|
repairing an earlier one.
|
|
|
|
|
|
|
|
|
|
Compatibility: the `project.cpp` of every sibling repository beside this
|
|
|
|
|
checkout (`../Crafter.*/project.cpp`) and of every user compiles against
|
|
|
|
|
what `interfaces/` exports and is loaded by the binary; the CLI, the
|
|
|
|
|
`CRAFTER_BUILD_*` variables, the cache an older version left under
|
|
|
|
|
`~/.cache/crafter.build/` and the `bin/` layout CI globs are contracts too.
|
docs: a release is a signed tag pushed with master
The README offered master builds as the `beta` branch, AGENTS.template.md
described the `latest` tag CI force-pushed, a release as a tag pushed
after master, and CI as running on every push to master, and the
repo-better-solution lens told reviewers that users get master through
`beta`.
The README now says that releases go to `stable`, the branch its install
commands pick even while the repo still holds the old `beta` branch.
AGENTS.template.md says that every pushed range adds a release entry and
goes out in one push with a signed tag on the commit master receives,
its last commit or, on the pull-request path, the merge, how to write
the entry, what every run checks before building and what a tag run also
checks, publishes and creates, what follows when one fails, what CI runs
for, and what becomes of `beta`; the lens says users get master through
releases on `stable`. The entry's rules are the owner's: at most three
sections, New, Fixes and Breaking, the most important item first and
nothing after them, and a version that is a major for a Breaking
section, a minor for New items and a patch for Fixes alone. The release
paragraph also gets the blank line that keeps it apart from the one on
local builds.
2026-11-02 11:44:35 +01:00
|
|
|
Users get master through releases on the Flatpak's `stable` branch. A
|
|
|
|
|
change an existing `project.cpp` does not survive is a
|
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
|
|
|
finding unless the range documents, in the README, what users must change.
|