Agent governance framework

The public gate is a Claude Code PreToolUse hook, which runs before a tool call executes. It is registered at user level on the Mac for the shell tool, so every shell command an agent runs on that machine, in every project, passes through it. For a public repo it scans the lines and messages of outgoing commits and pushes. For a deploy it scans every file the project serves, whatever the repo’s visibility; a project that hasn’t declared what it serves counts as serving everything. In every repo it refuses a committed defect tracker.

The hard problem was timing. The hook reads the staged index before the command runs, so git add X && git commit was checked against an index that didn’t contain X yet. The gate scanned nothing, allowed the call, and a third-party identifier reached a public repo. A probe showed the patterns were right; the gate simply couldn’t see the change.

Simulating git add would mean reimplementing pathspecs, and scanning the working tree would flag scratch work nobody was committing. So the gate refuses the shape: any call that stages and also commits or pushes is denied, and the refusal names the remedy (Fig. 1). It also refuses bulk pushes and archive refs, and if its own check throws, or GitHub can’t confirm a repo’s visibility, the command is held.

In September 2026 private material reached public repos: committed defect trackers carrying a third party’s name and words, and a third-party name in project files. Force-pushed commits survive as unreachable objects that can still be retrieved, so rewriting history in place was ruled out. Each affected repo was deleted and recreated with fresh history at the same URL, and its prior history went to an archive outside the project.

That left a quieter hazard. In one repo the removed commits still lived locally on nine tags and three archive branches, so one git push --tags would have republished them all, and the only guard was a sentence in a notes file.

The order mattered. Every removed commit was first confirmed in the outside archive by hash; then the local refs were deleted and the object store pruned; then two mechanical guards went in: the gate’s bulk-push refusal, and a pre-push hook in that repo that lets only the main branch and version tags leave, whoever pushes.

The containment model came out of a run of failures; it wasn’t designed up front. In June 2026, preparing a private repo for public release turned up private notes that had built up in its git history, caught before it went public. The safeguard had been a habit, checking what’s staged before each commit. Its replacement was a rule: ignore private files by location, and audit with git ls-files.

Two days later the rule failed silently. A .gitignore line written with an inline comment became a literal pattern, the private folder was no longer ignored, and git add -A staged it. Only a manual audit caught it before the commit.

So the safeguard changed kind. The canon moved out of every repo and is read by reference, never copied. The sync machinery built that morning to keep copies current was deleted the same day: there were no copies left to keep current.

Where structure can’t reach, the ladder steps back down to a fail-closed check. One project’s dev-only tooling needs a bundler config outside the folder the project ignores, and it passes every content scan, so the checker refuses that path in a public repo by where it sits, not by what it contains.

Two questions come up whenever an agent edits a governed codebase: may I change this, and why is it this way?

In the rules, a small tool stamps an append-only ID on each ruling without reading the prose. A ruling inserted mid-section takes the next free number, so existing citations never move; stripping the markers restores the file byte for byte (Fig. 3). History headings carry their section address, so --why 4.2 narrows a search to that section’s history and ranks lines by keyword. Where a section has to be inferred from its title, the audit says so: a missing label becomes a finding, not a silent guess.

In code, a decision comment carries a tier marker, most of them dated: owner-decided, agent-decided (also how an unmarked comment is read), unsettled, or retired but kept on record. The tiers were designed to be safe in public repos; what the gate flags is wording that attributes a decision to a person.

File headers state what a file does, what calls it and what it writes. That rule came from an incident: a stale header described an old design, and a later session ran a middle pipeline step that overwrote a hand-verified data table. All 244 of FIRST LIGHT’s source files now carry one.

Procedures that matter only when something specific happens moved into Claude Code skills: the harness keeps a one-line description in view and loads the full text only when it matches. Of the canon’s files, 160,633 bytes load at session start and 563,884 do not: 122,428 bytes of on-demand procedure (including 1,289 lines of postmortems from third-party platforms), the 364,121-byte dated history and the retired 77,335-byte process file.

The trade-off cut the other way once. Build procedure, deferred until a build came up, got read late in a long session right before a ship, so it moved back into the bootstrap and was trimmed.