Engineering and Change-Control Guards
Last updated: November 20, 2026
The rules in the rest of this section only matter if the software that enforces them stays intact. This page covers the guards on the platform itself: what stops a code change, or an AI coding assistant, from weakening a gate, losing an editor’s work or leaking a secret. We describe their purpose. We do not publish how to get around them.
Commit-time guards
Before a change enters our repository, a chain of checks runs on it. As of November 20, 2026, they include:
| Guard | Purpose | Blocks or warns |
|---|---|---|
| Security scan | Every commit passes an automated scan for exposed secrets and known dangerous code patterns | Blocks on the serious findings; lower-severity findings warn |
| Canonical-file guard | A commit may not empty or drastically shrink an index file that other tools depend on | Blocks |
| Rules-sync check | Generated copies of our rules, used by other tools, must match their source | Blocks |
| Commit-lane guard | Content changes and code changes go in separate commits unless the commit declares otherwise | Blocks |
| Update-sibling check | A dated “update” copy of a profile that already exists suggests an edit should have been made in place | Warns |
Secrets are kept out of the codebase and version control; the scan is one layer of that.
The lanes
Content and code share one repository, one main branch and one test suite. A commit that mixes both is hard to review and hard to revert: undoing the code half takes a content edit with it. So each commit declares a lane: content, documentation or code. A commit that mixes lanes must say so, and the continuous-integration check on a pull request refuses a mixed commit that lacks the declaration. One classifier decides a change’s lane for both the commit hook and CI, so the two cannot disagree.
Guards on AI coding assistants
Two guards apply to AI assistants working on our code.
Protected files. Our rule files, the instruction files that AI tools read, and the settings that configure them are protected. A hook at the tool boundary refuses an AI write to them. We added it because a rule that depends on a model remembering it is not enforced. An AI may edit a protected file only on an explicit human instruction that names the change, given in the session that makes the edit. The authorization is recorded where it was used, so a later reader can see that a person asked. Git history shows only that an AI made an edit, never that a human requested it.
Branch switching. Our editing console saves into the main checkout, so a stray branch there strands saved work. A second hook refuses an AI assistant switching branches in that checkout. It exists because that happened once, on November 16, 2026.
The related written rule is that code sessions work in isolated worktrees, not in the shared checkout. A worktree is a separate working copy of the repository on its own branch, created from the latest published state. The shared checkout belongs to the editing console and the content stream. Four working rules follow:
- Changes you did not make are not yours. Never revert, stash or tidy them.
- Never stage everything at once. Stage explicit paths.
- Never switch branches in the shared checkout without asking.
- Commit your own work promptly, so it is not mistaken for someone else’s.
Continuous integration
Every pull request runs a workflow of 7 jobs, defined in .github/workflows/ca-tests.yml. Four are required to pass before anything merges to the main branch, under strict settings:
| Required job | What it runs |
|---|---|
pytest (non-integration) |
The code test suite |
pytest (corpus) |
Tests that read the live content corpus |
vitest (gui/tests/js) |
JavaScript unit tests |
playwright (gui/tests/e2e) |
End-to-end tests of the real editing console |
The other three classify the change’s lane, check commit lanes across the pull request, and check the site theme’s computed styles.
One design point matters. Steps that do not apply to a change, such as the code suite on a content-only edit, are skipped at the step level, not by skipping the whole job. A job skipped whole never reports a status, and a required check that never reports blocks every merge. A test holds that shape in place.
Bite tests
A guard that has never been shown to fail is a claim, not a guard. So we require a bite test for each guard: a test that plants the fault the guard exists to catch and asserts the guard fails. A meta-test finds every test module whose name marks it as a guard, a registry, a parity check, a ratchet or a reachability check. It fails unless the module contains at least one test that plants a fault.
This is not yet complete. As of November 20, 2026, the meta-test lists 26 modules as a known backlog, each marked as debt. The list is two-way: a module that gains a bite test, or disappears, fails the check until its entry is removed. The backlog can only shrink.
Ratchet baselines
Some defects cannot be fixed all at once, and a rule that failed on all of them would be ignored. A ratchet records today’s count as a baseline and fails on any regression:
- Wikilinks. No new broken
[[slug]]link may enter the knowledge base. The existing ones are recorded, and fixing links only lowers the number. - Hard-coded counts. Manuals may not gain a new hard-coded corpus count such as “1,039 profiles”, because such numbers go stale. The count must sit beside the command that measures it.
related:targets. This one is a plain gate rather than a baseline: everyrelated:entry must resolve to a document or sit on a short, reviewed allowlist.- Score designations. A table of exemptions to the rule that a stated designation must compute from its scores is pinned empty. Adding an entry is a reviewed decision.
The baselines are shrink-only. When a defect is fixed, its entry must be deleted.
How an AI builds code here
Our code-building agent, described in The Code Builder Agent, works inside these guards. It implements one written brief, in its own worktree, touching only the files the brief lists. It adds a bite test for every guard it writes, runs the named tests and the full code suite, and makes one commit on its own branch. It does not push, merge or edit protected files. A person decides what happens to the branch next.
Factual correction requests: If you believe information in this page is incorrect, please contact factcheck@citizenanalyst.ai with your name (optional), the specific claim, and any supporting documentation. We review all submissions and correct verified errors promptly.
