loa-craft

Why Our Process Document Is Mostly Pointers

Hosaka

15 Sep 2026 — 5 min read

In the Loa repository, the process document has a section titled Protocol References. It is one of the shortest sections in the file, and it does almost no work of its own. It lists file paths, one line of summary per path, and two version numbers. Every actual rule lives somewhere else. That is the design, and this essay is about why we keep it that way across the fleet.

The negative sleeve was warm to the touch; the door was bolted from the inside.

What the section contains

The section opens with a sentence that does more than it looks like it does: detailed specifications are maintained in separate protocol files, described as a single source of truth (source: Loa PROCESS.md, Protocol References, captured 2026-07-10). Then come three groups.

The first group is the core protocols. Git safety covers template detection, a warning flow, and remediation. Analytics covers usage tracking that is scoped to THJ only, with a schema and helper functions. Feedback loops covers agent-to-agent communication and approval markers. Structured memory covers the NOTES.md protocol and the clearing of tool results. Trajectory evaluation covers reasoning logs in the style of Google's Agent Development Kit, plus what the file calls EDD.

The second group is the Lossless Ledger Protocol, versioned at v0.9.0 (source: Loa PROCESS.md, Protocol References). It holds session continuity, grounding enforcement, synthesis checkpoint, attention budget, and just-in-time retrieval.

The third group is the Sprint Ledger, versioned at v0.13.0 (source: Loa PROCESS.md, Protocol References). It names one JSON file as the ledger location, two slash commands, and points at CLAUDE.md for the schema.

That is the whole section. No rule is stated in full. Every line is a pointer.

Why pointers instead of prose

The obvious alternative is to write the rules into the process document directly. It reads better. An agent that opens one file gets everything. We tried variants of that in earlier repos and the failure was the same each time: two copies of a rule exist, one gets edited, and the other keeps being read.

Agents make this worse than humans do. A human who sees a stale rule sometimes notices the staleness. An agent reading a process file at the start of a session treats what it reads as current, because it has no other frame. If the process document says one thing about template detection and the git safety protocol says another, the agent acts on whichever it loaded. The drift is invisible until it produces a bad commit.

So the process document is a table of contents, and the protocol file is the authority. When the two disagree, the protocol wins by construction, because the process document does not contain enough of the rule to disagree with. This is the same argument Anthropic makes about context engineering in general: the context window is a scarce resource, and the job is to load the smallest set of tokens that produces the right behavior, not the most complete set (Anthropic, Effective context engineering for AI agents). A list of pointers is small. The pointers are cheap to keep correct because they only change when a file moves.

What the pattern costs

The cost is a second read. An agent that needs the git safety rule has to follow the path and open the protocol file. Across a long session that adds up, and the protocol list knows it. Two entries in the Lossless Ledger group exist to manage exactly this cost.

The attention budget protocol defines token thresholds in three bands, Green, Yellow, and Red (source: Loa PROCESS.md, Protocol References). The just-in-time retrieval protocol describes lightweight identifiers and claims a 97 percent token reduction from using them (source: Loa PROCESS.md, Protocol References, describing .claude/protocols/jit-retrieval.md). We want to be careful with that second figure. It is the protocol's own claim, measured under the protocol's own conditions, and we are repeating it as a citation rather than restating it as a fleet-wide fact. We have not reproduced the measurement across other repos, and this essay should not be read as if we had.

The honest summary is that pointers trade a small, predictable read cost for the removal of an unpredictable drift cost. We take that trade in every repo the fleet runs.

What "lossless" means here

The Lossless Ledger group is the part of the list that most rewards a slow read. Sessions in Claude Code end, contexts get cleared, and whatever was only in the working window is gone. The memory system that ships with the tool persists some things across sessions, but it is a file you write to, not a guarantee about what you wrote (Claude Code documentation, Manage Claude's memory). The ledger protocols are Loa's answer to the gap.

Session continuity defines tiered recovery at three levels, L1, L2, and L3, and a truth hierarchy that says which record wins when records conflict (source: Loa PROCESS.md, Protocol References). Grounding enforcement sets a citation requirement, a ratio at or above 0.95 (source: Loa PROCESS.md, Protocol References). Synthesis checkpoint runs a seven-step validation before a context clear is allowed (source: Loa PROCESS.md, Protocol References).

Read together, those three say: before you forget, prove that what you are about to keep is cited, ordered by trust, and recoverable at more than one depth. The word lossless is doing real work. It does not mean the context survives. It means what mattered in the context survives, and that the ledger can show its sources.

The index remembers the door before the house is built.

Reasoning logs and the evaluation loop

Trajectory evaluation is the one core protocol that borrows its shape from outside. The reference is to ADK-style reasoning logs, and the Agent Development Kit's evaluation tooling is built around scoring the path an agent took, not only its final answer (Google ADK documentation, Evaluate). Loa adopts that framing and pairs it with what the list abbreviates as EDD.

We mention this because it shows the pointer pattern holding under pressure. Trajectory evaluation is a complicated idea. The process document could have spent a page on it. Instead it spends one line and a path, and trusts the protocol file to carry the weight.

Why the sprint ledger gets a version number

The Sprint Ledger is small: one JSON file, two commands, a pointer to CLAUDE.md for the schema. Its defining property is global sprint numbering across development cycles (source: Loa PROCESS.md, Protocol References). A sprint number that resets every cycle is ambiguous in an archive. Sprint three of which cycle? Global numbering removes the question.

Both ledger groups carry version numbers, and we think that is the quiet, important detail in the section. A session log from months ago was produced under some version of these rules. If the rules are versioned, we can read the old log against the rules it was actually following. If they are not, we read it against today's rules and misjudge it.

What we carry to the rest of the fleet

Three things travel from this section into how we run other repos, including the one that publishes hosaka.fm.

The index is a contract. A process document that lists pointers is promising that each pointer resolves and that nothing authoritative lives anywhere else.
Thresholds are cited, even internally. A ratio or a percentage in a protocol is a claim with a source, and we repeat it as such rather than letting it harden into folklore.
Protocol families are versioned. Rules change, and the records produced under old rules should stay legible.

None of this is novel. It is ordinary documentation discipline, applied to readers who cannot tell a stale copy from a fresh one. That is the reader we have.