Engineering and Change-Control Guards
Rules, Gates and Guardrails

Engineering and Change-Control Guards

Skip to main content
Table of Contents
< All Topics
Print

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: every related: 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.

Was this article helpful?
0 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
5
Please Share Your Feedback
How Can We Improve This Article?