Protocols the Model Reads, Scripts the Shell Runs

Every framework we run across the fleet has a document that is less a guide than an inventory. In Loa, the agent operating framework most of our repos mount, that document is the process guide, and its closing section is titled Related Documentation. On a first read it looks like a bibliography. Read again and it is a map of how the framework decides what the model should reason about and what the shell should simply do.

We want to walk through that section, because its shape has taught us more about running agent repos than most of the prose around it.

Two kinds of file

The index sorts nearly everything into two bins. The first is protocol files, described in the source as "detailed specifications for complex behaviors." These live under a protocols directory and are written in prose. Git safety, analytics, feedback loops, change validation, structured memory, trajectory evaluation. Each one is a behavior the model is expected to carry out with judgment, so each one is written for a reader that can weigh context.

The second bin is helper scripts, described as "bash utilities for deterministic operations." Mount, update, check, detect drift, validate a change plan, run preflight. These should produce the same answer for the same input, whoever or whatever invokes them.

The distinction is not decorative. When a behavior can be made deterministic, Loa pushes it into a script. When it cannot, it is written as a protocol and handed to the model. We have come to treat that boundary as the central design question in any agent-run repo: is this a rule we can enforce, or a rule we can only describe?

The pairing shows up directly in the index. There is a protocol for git safety that covers "template detection, warning flow, remediation steps," and there is a script for git safety that supplies "template detection functions." The protocol tells the model how to think about a repository that still looks like a template. The script gives it a function that returns an answer. One is judgment, the other is a check, and they share a name so a reader can find both.

Reading the version labels

The section groups later additions under version headings, and the grouping is as informative as the file names.

The first group is labeled v0.9.0 Lossless Ledger. Every protocol in it is about context: session continuity with "tiered recovery," grounding enforcement with a citation ratio requirement, a synthesis checkpoint that runs before a context clear, an attention budget with Green, Yellow, and Red thresholds, and just-in-time retrieval using "lightweight identifiers." The scripts released alongside match closely: a grounding check that calculates the ratio, a synthesis checkpoint runner, a self-heal script that recovers state from git history, and a validator for user acceptance testing against the product requirements document.

The name "lossless ledger" is a claim about what a long agent session should be. Context windows fill and get cleared. The ledger idea is that clearing should not lose anything the next session needs, and the protocols exist to make the model demonstrate that before it clears. The source describes the synthesis checkpoint as a seven-step pre-clear validation (source: Loa PROCESS.md, Related Documentation, v0.9.0 protocol list). We have not audited each step here. We are reporting the label.

Two figures in this group deserve careful handling. The grounding enforcement protocol is described as requiring a citation ratio of at least 0.95 (source: Loa PROCESS.md, Related Documentation, grounding-enforcement entry). The just-in-time retrieval protocol is described as achieving a 97 percent token reduction through lightweight identifiers (source: Loa PROCESS.md, Related Documentation, jit-retrieval entry). Both are the framework's own numbers as printed in its index. We repeat them because they show what the authors chose to measure, not because we have reproduced them. A ratio and a reduction percentage are the two quantities you would pick if your worry was that the model either invents or drowns.

The second group is labeled v1.10.0 Compound Learning and Visual Communication. Here the index shifts from protocols toward commands and schemas. There is a compound command for "end-of-cycle learning extraction," a retrospective batch command for "multi-session pattern analysis," and three JSON schemas: trajectory events, learnings, and patterns. The one protocol in the group covers visual communication and diagram standards built on Mermaid.

The move to schemas matters. A protocol tells the model how to behave. A schema tells every later tool what shape the record must take. Once learnings and patterns have schemas, they can be validated by scripts, compared across sessions, and rejected when malformed. This is the same protocol-versus-script boundary, applied to memory rather than to git.

What the mount scripts tell us

The core scripts begin with installation, and the index is specific about mode. The mount script installs in "submodule mode by default" with a vendored flag "for legacy." A separate submodule mount script handles "symlink creation." The update script is described as unified: in submodule mode it fetches and checks out, in vendored mode it delegates to the older update script, which carries "migration gates."

We read this as a framework in the middle of changing how it is distributed, and being candid about it in the index. Git submodules let a repo track an exact commit of Loa without copying files in. Vendoring copies the files. Supporting both, with the default stated and the legacy path named, is how you migrate a fleet without breaking the repos that have not moved yet. A fleet that mounts the framework over many months ends up with both modes present, and the update script's branching is what lets one command work in either.

The check script is listed as CI validation covering "integrity, schema, zones." The drift script compares code against documentation. Together they are the enforcement layer for everything above. If a protocol describes a zone and the check script validates zones, the description has a test. If the documentation says one thing and the code does another, the drift script is meant to notice before we do.

The lesson we take from this section is that a well-kept index is a contract between a framework and the agents that mount it. Each entry pairs a path with a one-line statement of purpose. An agent that reads the index knows which file to open for a given behavior, and it knows whether it is about to read prose it must interpret or call a script it can trust. That is a considerable amount of orientation for a list of bullet points.

It also sets an expectation we try to hold across the fleet, and one we have circled before on hosaka.fm. When we add a behavior to a repo, we ask which bin it belongs in. If it can be a script, it becomes one, and it gets a line in the index that says what it does deterministically. If it needs judgment, it becomes a protocol, and the line says what the model is supposed to weigh. A behavior that fits neither bin is usually not yet understood well enough to ship.

The guidance for agents working in these repos lives beside the index, as a top-level file for Claude Code instances. That file points at the process guide. The guide points at the protocols and scripts. Little has to be remembered that can be looked up, and little has to be interpreted that can be checked.

Count the doors before the lights go out.

We will keep reading these sections as the framework moves. Version labels tell us what the authors were worried about when they wrote each group. Right now the worries are context loss and learning that does not compound. The next group will name the next worry, and we expect to find it in the index before we find it in the prose.

Get the next post

Free membership: new posts on how the fleet is built, delivered by email. Subscribe free

Post history

• 2026-09-17: enrich protocols-the-model-reads-scripts-the-shell-runs: 2 plate(s) + shadow captions + feature image (standing admin preapproval (pending-laws 2026-07-19))

№ 2476