A parser, not a reader
Markers are extracted by a real scanner and the grammar is checked — a node id must match ZONE.function or AIRSPACE://ZONE.function or it's rejected. The map is structured data, validated as data.
Why gndctrl
It's software, not a prompt.
A prompt file — a CLAUDE.md, an
AGENTS.md, a coding-standards doc — is text you drop into a
chat box, and every agent gets its own copy to skip. gndctrl is a program that reads your
code. The markers and the .gndctrl file aren't instructions
the model follows out of goodwill — they're a data format with a parser, a schema validator,
an auditor, a dependency resolver, and a runtime enforcer behind them, giving every agent in
the fleet one shared, enforced rulebook. You can copy a prompt into any tool in five
seconds. You can't copy enforcement — enforcement has to run.
What's actually in the package
A schema, not conventions
Six stability tiers, five ranked agent classes, five zone types — all validated against fixed sets. An unknown tier or mistyped class is a hard error, not a line quietly ignored. Clearance can be computed because the inputs are typed.
A pre-flight resolver
gndctrl preflight walks the transitive dependency chain for the zones a task touches and decides, in code, whether the agent's weight class clears it — returning the reason when it doesn't. The clearance brief is a function's return value, not a vibe.
A scaffolder
gndctrl init writes the starting .gndctrl and logbook/, auto-detecting single vs. fleet mode.
An auditor with CI exit codes
gndctrl audit runs deterministic integrity checks across the
whole tree and exits non-zero on failure — wire it into CI and a broken governance map fails
the build. It speaks --format json for pipelines.
| Check | What it catches |
|---|---|
| A1 | Zone START/END markers that don't pair up |
| A2 | A node pointing at a zone that doesn't exist |
| A3 | A @gndctrl:node CRID with no matching logbook entry |
| A4 | A malformed CRID |
| A6 | Dependency resolution — including circular-dependency detection |
| A9 | A zone that depends on a deprecated zone |
| A10 | Zone-index drift — the map and the code have diverged |
Real audit logs from the pyChisel deployment read: "Files scanned: 125 · Zones: 4 · Nodes: 2 · ✓ Clean." That's a program executing over a codebase — not a model promising it read the rules.
A runtime tripwire
The enforcement hook sits in front of every file-writing action an agent takes: it locates the
governing .gndctrl, confirms the agent actually read it this
session, and returns a structured deny with a reason if it
didn't — deterministically, every time. The pattern is agent-agnostic: the reference
implementation runs as a pre-tool hook on pyChisel's fleet, but the same gate drops in front
of any agent runtime that exposes a tool-call boundary.
It fails closed on the one thing it's certain about ("you didn't read the map") and open on everything else, so it gates without getting underfoot. A companion tripwire does the same for commands: a data-driven ops-hazard registry maps dangerous command patterns to the document that must be read before they run. Governance for the shell, not just the editor — and because the hazards are data, adding one is editing a registry, never the hook.
Why this is the whole point: an instruction file is portable precisely because it's inert — it does the same nothing everywhere. gndctrl is worth downloading because it parses your governance, validates it, fails your build when it rots, and blocks the edit when an agent skips the map.
Plain agent + prompt file vs. gndctrl
| Plain agent + prompt file | gndctrl | |
|---|---|---|
| Rules | Advice the agent can skip | Enforced at the tool / commit / session layer (edits and commands) |
| Architecture awareness | Infers it by reading files | Reads a zone map; knows where it's standing |
| Memory across sessions | None — re-learns by breaking things | Logbook + decision_log + known_solutions, in-repo |
| Works across providers | Re-write rules per tool | One shared rulebook + memory, any agent, via weight classes |
| Context cost | Dump the whole repo | ~1–4k-token targeted pre-flight |
| Scale | Breaks down with parallel agents | Single → fleet on the same mental model |
The four differentiators — each with its proof
1 · Enforcement, not advice
Sensitive/locked zones and the pre-tool read-gate block the edit. Proven in production: on pyChisel, agents are denied edits to a zone until they've read it.
2 · Persistent institutional memory
The CRID/logbook system means the next agent — or the next model entirely — starts informed about the landmines, instead of stepping on them.
3 · Provider-agnostic & shared
Weight classes map any agent to a tier, and every agent reads and writes the same map and logbook — so a mixed fleet of Claude, Gemini, Copilot and local models shares one set of guardrails and one memory, not one rulebook per tool.
4 · Scales solo → fleet
Single mode is one .gndctrl file with zero ceremony. Fleet mode adds airspaces, cross-airspace dependencies, master governance, and a zone-lock table — the same concepts, a bigger map.
You can't paste enforcement into a chat box.
It's a tool you run — in CI, in a commit hook, and in front of the agent. The spec works today by hand with any agent; the CLI and public repo are the packaging on top — now public.
How gndctrl lowers token spend