.gndctrl
One file at the project root. A zone registry: each zone is a set of path patterns plus its stability tier, dependencies, gotchas, decisions, and logbook pointers.
How it works
Seven mechanisms, all in the repo.
gndctrl gives the codebase a voice that survives session resets and tool switches, and makes the important rules non-optional. Here's the machine behind that — from the markers an agent reads to the runtime gate it can't talk its way past.
1 · The codebase annotates itself
Governance lives in three layers, in the repo.
@gndctrl:zone
Inline START / END markers that wrap a region of a file when one file spans more than one zone.
@gndctrl:node
A marker on a single non-obvious function: its risk level, the external systems it touches=[...], and a crid= linking it to a logbook entry.
The point: an agent doesn't have to infer the architecture by reading 50 files. It reads a map.
2 · Stability tiers — clearance, like airspace
Every zone carries one of six tiers. Each maps to an air-traffic-control class — that's the whole metaphor: how controlled is this airspace? The tier isn't decoration; it changes what the tooling allows, not just what it suggests.
| Tier | ATC equivalent | What an agent may do |
|---|---|---|
| experimental | Uncontrolled | Act freely |
| active | Class E | Normal work; verify deps aren't broken |
| stable | Class C/D | Read the zone doc before structural changes |
| sensitive | Restricted | Read full zone + dependency-chain docs; gated by agent capability |
| locked | Prohibited | Humans only — agent surfaces a diff for review, never edits |
| deprecated | Decommissioned | No new dependencies; suggest the migration path |
3 · Pre-flight — load the right context, cheaply
Before an agent works, it runs a short, bounded sequence: load the
.gndctrl, find the zone(s) the task touches, pull only those
zones' dependency docs and logbook entries, check it's allowed in, and issue a one-paragraph
clearance brief.
This is also where the token economy comes from. Instead of dumping a 40k–200k-token codebase into context to "understand" it, the agent reads a ~1–4k-token map and pulls only the relevant section. Targeted, not exhaustive — once per session, not per question. How this cuts drift and spend →
4 · Persistent memory — the logbook
Three durable stores, all in the repo — shared context that every agent reads and writes, whatever provider it is, so memory carries across sessions and across a mixed fleet.
Logbook
CRID-indexed, per-function institutional memory: the workaround, the landmine, "what breaks if you change this." Loaded on demand at pre-flight.
decision_log
Why an architectural choice was made, what was considered, what it affects.
known_solutions
Generalizable fixes, so a solved problem stays solved across the team or fleet.
A CRID (Control Record ID, e.g. PMT-20260430-001) is the immutable link between a marker in the code and its logbook entry. The code says what; the logbook says why, and what not to touch.
5 · Enforcement — advice vs. a hard gate
This is the line between gndctrl and a prompt file. Enforcement is two-layer.
Soft
The contract every agent loads tells it the rules — provider-agnostic, the same across tools.
Hard
Platform-level guardrails the agent cannot talk its way past: file watches, commit hooks, session scoping, and tool-call interception.
This is live, not theoretical. On pyChisel — the platform
where gndctrl is built and hardened — a pre-tool hook sits in front of every agent edit. If
an agent tries to modify a file inside a governed zone before it has read that zone's
.gndctrl, the edit is denied: the agent is
handed the reason and told to read the map first, then retry. An agent physically cannot
"act first, read the architecture last" — the most common, most expensive agent failure is
removed at the tool layer, not requested in a prompt.
Reading the map clears an ordinary edit — but not every gate lifts on a read. A
locked zone stays denied even after the agent has
read it: locked means human clearance only, so an agent can't read-then-edit its way into
legal text or a compliance doc — it can only surface the change as a diff and stop. The same
hook enforces one agent per zone (a live lock held by another session blocks
the edit and names the holder) and a zone's minimum_agent_class
floor — so a too-light agent is turned away at the tool call itself, not merely advised at
pre-flight.
And enforcement isn't limited to edits. The most destructive things an agent can do are often commands: restarting a shared service, reloading authoritative DNS, recreating a container. A second tripwire sits in front of the agent's shell — when a command matches a governed operational hazard, it's denied until the agent has read the document describing that hazard's blast radius and recovery. This came straight out of a real incident on pyChisel: a routine service-restart quietly changed a core container's internal address and cut every user off. The hazard was documented — but nothing surfaced it, because edits were gated and commands were not. The fix shipped the same day. Now both are gated.
A third hook runs the other direction — not a denial but a briefing. At the start of every session it scans for governed projects and injects the map up front: which projects are under gndctrl, and the standing rules — read before you edit, locked zones are human-clearance only, one agent per zone. Without it, an agent only discovers governance when its first edit is denied; with it, the tripwires become the backstop instead of the introduction.
6 · Weight classes — provider-agnostic capability gating
Agents differ in capability, so zones declare a minimum_agent_class
— a floor, not a ceiling. The rules are written once and apply to
any provider, without rewriting your guardrails per tool.
| Weight class | Examples |
|---|---|
| Super | Frontier reasoning (Claude Opus) |
| Heavy | Claude Sonnet, large capable models |
| Medium | Gemini, GPT-class mid-size, Copilot |
| Light | Small fast local models (3–7B) |
| Ultralight | Scripted / rule-based (gndctrl's own Auditor / Writer) |
A heavier agent can always enter a lighter zone; a too-light agent is held at pre-flight until a capable one is available.
7 · It maintains itself
gndctrl ships two Ultralight agents so the system doesn't rot.
Auditor
Validates that every marker is well-formed, every @gndctrl:node has a logbook entry, every zone resolves. Drift in the governance itself gets caught.
Writer
Appends decisions and creates logbook entries as work happens — so memory is captured in the same motion as the change, not as a forgotten end-of-session chore.
The mental model never changes.
Single mode is one .gndctrl file with zero ceremony. Fleet mode adds airspaces, cross-airspace dependencies, and a zone-lock table for parallel agents — the same concepts, a bigger map.