CI workflows and local checks

GitHub runs no check on a pull request. The twelve workflows that used to carry a pull_request trigger lost it on 2026-10-06, and entity-writes.yml lost it when it was caught growing the trigger back hours later; the earlier pr.yml gate and the automatic review were already gone. The local check runner replaced the whole pull-request gate:

./compass.sh check

compass check reads the branch diff against origin/main, classifies every changed path against the decision tree in build/scripts/local_checks.py, runs the checks that class needs, and writes build/output/local_checks/report.md — one table of every check with its result and time, and a Fix these first section naming each failure, the command that reproduces it, the command that fixes it, and the tail of its log. The exit code is 0 when every selected check passed.

The runner is the gate for two reasons. GitHub checks arrived minutes after a push, so a broken change waited behind a queue for a verdict a workstation reaches in seconds. And a workflow could only fire on the paths it named; a change matching no workflow saw no check at all, while the runner's catch-all sends an unclassified path through everything.

One table, in build/scripts/local_checks.py, maps a changed path to a change class. A check runs when its class matched the change and, when the check declares its own path patterns, one of them matched too.

Three rules follow from the table:

1. A mixed change takes the union. A model edit that also regenerates headers is a docs and modeling and cpp change, and runs the checks of all three.
2. A path no rule claims asks for everything. A change this table cannot classify is a change it cannot vouch for, and the cost of the extra run is smaller than the cost of the break it hides.
3. A model or template change does not by itself compile the tree. The regeneration writes the generated C++ into the tree, so that file appears in the diff and the cpp class does the build. A model change whose regeneration is missing fails component-drift first, which is the point.

The classes and the heavy tier:

pgtap runs projects/ores.sql/test/run_tests.sh over the database the check above it rebuilt. It stays in the sql class alone and stays after db, because it reads the schema that check recreates. Every suite writes the reference data it reads and rolls it back, so the corpus passes on a database that carries no tenant data beyond the seed.

A documentation-only change therefore runs compass site page and the doc corpus checks and never reaches the compiler.

A change that compiles only into test binaries skips the fleet checks: db, ticks-smoke and step-consumers. The runner decides this after build passes. It reads ninja -t deps and finds the targets that compile each changed path. It skips the three checks only when all of these are true:

• Every path that selects a fleet check is a C++ source or header.
• The dependency log knows every such path.
• Every target that compiles such a path is a .tests binary.
• No changed path is unclassified.

A new file, a CMakeLists.txt or a SQL script keeps the fleet checks, because the log cannot vouch for it. The report names each skipped check and the test binaries that caused the skip. --all and --only skip nothing.

db has one more condition. The runner skips it only when the database's schema fingerprint equals the checkout's, as compass env status --json reports them. Main moves under a branch, and a database from before the move fails the suites that read the new tables. When the runner skips db, ctest runs with the fleet in the state the developer left it.

Three details matter when reading the report. The change is measured from the merge base with origin/main, including uncommitted and untracked files, so the runner is useful mid-work as well as before a raise, and another author's merge onto main never reads as this branch's change. The tangle checks (tangle-templates, tangle-shell, tangle-http) re-run the tangle and then ask git whether the tree moved: they fail when the committed output is stale, which is the same contract the retired workflows had. And the drift family (component-drift, model-drift, the tangles) compares the regenerated tree against HEAD, so it needs a committed tree — an uncommitted edit to any file reads as drift. Commit before running the modeling or codegen classes. component-drift regenerates only the registry components whose models this branch changed, read from the diff against the base; a change under projects/ores.codegen/ regenerates them all, because the generator and its templates decide every component's output. Keeping the rest of the registry clean belongs to the drift-sweep check, not to this branch's component-drift.

Nothing on a pull request. Ten workflows keep their own triggers:

The twelve retired triggers were codegen-drift, codegen-sweep, doc-lint, dsh-environment, entity-writes, event-registrar-composition, header-hygiene, populate-reference-drift, rls-system-tenant-widenings, shell-script-drift, template-drift and typescript. Each keeps its push to main trigger, so a defect that escapes the runner still shows on main the moment it lands.

• Absorb PR checks locally: targeted checks, local review, CDash submissions — the story this analysis fed.
• Run every check locally in one report — the story that built the runner.
• Analyse all CI workflows and map each check to its local equivalent — the inventory this document replaced.
• PR Raise — the skill that runs compass check before raising.
• Knowledge — the knowledge index.

The heavy tier is the only part of the runner that is not self-contained, and its three checks do not want the same thing:

The two constraints pull against each other, because compass services stop stops the NATS server as well as the services it fronts. Stopping the target for db therefore takes down the server ctest needs, and leaving it up means db recreate --kill loses its race: it terminates the service backends and they reconnect before the recount, so the recreate refuses on a handful of live connections.

The environment that satisfies both is the NATS server running with every service stopped:

./compass.sh services stop
systemctl --user start nats-server-festive-dijkstra.service   # or busctl, see ORES_USE_BUSCTL
./compass.sh check

The runner states none of this and enforces none of it. It is written here because a machine that has just been used for anything else will fail one of the two, and the failure reads as a defect in the change rather than in the environment.