AOCI-CODE

AOCI-CODE keeps a persistent, Git-versioned map of a repository that a coding agent reads before it touches anything. It is one CGO-free Go binary that works as a CLI and as a stdio MCP server exposing exactly nine tools, and what it governs is plain text: a Root declaring which Volumes take part, a Meta carrying the tag dictionary and the authoring rules, a Code Volume with one FRAS line per managed file, and an optional Database Volume built from accepted schema evidence. Each line records what an object is responsible for (F), what has to be read with it (R), what callers may depend on (A) and the constraints that cannot be inferred from the code (S). The model owns meaning; the binary owns governance — scope, the Baseline, source digests, structural validation, cross-process locks and compare-and-swap writes, the ledger, recovery, and an attestation that proves a complete index really was delivered. The README gives the licence as FSL-1.1-MIT — Fair Source, source-available rather than an OSI licence.

Who built itThe repository belongs to the aoci-spec organization rather than to a personal account, and the commits split unevenly inside it: 163 of 193 carry the name alkor2000, and 155 of those are linked to that GitHub account. dayebishouji accounts for 25, funfitx for 3 and DaisyHunter for 1, while 161 of the 193 commits carry a co-author trailer and 153 of those name a Claude model. Around them sit 689 stars, 118 forks and 13 open issues.

1. 01

   Seventeen release candidates, and a version line that never left 0.1.0

   The repository was created on 2026-08-08, and its first commit the same day is titled "chore: initial public release candidate" — which turns out to describe the whole project. In 52 days it took 193 commits, 109 of them in August and 84 in September, and published 17 releases, every one of them marked prerelease: v0.1.0-rc1 on 2026-08-08 through v0.1.0-rc17 on 2026-09-29. Nothing has ever been promoted out of the release-candidate line. The authorship is more interesting than the version number: 161 of the 193 commits carry a co-author trailer, and 153 of those name a Claude model — Fable 5.1 seventy-one times, Opus 5 sixty-seven, Fable 5 thirteen times and Opus 5.5 twice. The repository is owned by the aoci-spec organization, 155 commits are linked to alkor2000, 25 to dayebishouji, three to funfitx and one to DaisyHunter, with 689 stars and 118 forks around them.

2. 02

   The contracts are files, and the pull request template measures against them

   The repository rule in AGENTS.md is one line long: "Public runtime contracts live under spec/public/." That directory holds 20 plain-text documents and 179 KB, led by a 32 KB cognition-volumes contract, a 17.9 KB overview-delivery contract, a 15.5 KB database-authoring contract and a 13.3 KB refresh contract. What makes them contracts rather than documentation is that both ends are testable. AGENTS.md also fixes the binary name, the nine-tool MCP surface and the reservation of stdout for JSON-RPC, while every pull request body opens with an "Affected public contracts" checklist whose boxes are exactly those axes: MCP names and response shapes, CLI commands, flags and exit codes, spec/public/ text, the machine vocabulary in internal/machinecontract, and index, Baseline, receipt or transaction identity. The Meta Volume goes further and declares #FRAS-v2-Limits-Authority: machine-contract; the README calls that the load-bearing line, because "the field limits belong to the binary, not to this text, so a project cannot widen them by editing its own Meta."

3. 03

   Four black-box suites, and a gate table that says when green means nothing

   AGENTS.md states that make fast is the Tier-0 gate and is "never sufficient evidence on its own", and lists five gates that run only under make full — clean-room smoke, licenses, race, vuln and database integration — with the note that changing a machine default once broke clean-room smoke alone while every fast gate stayed green. Above the unit tests sit four black-box suites under scripts/blackbox/ that drive a built binary strictly from outside the process: 46 read-only conformance checks of the MCP wire surface, 64 fault-injection scenarios over cursor tampering, crash recovery and racing writers, a lifecycle suite over three frozen fixture repositories (a TypeScript app, a Python service with MySQL, and a 453-file layered service), and an upgrade axis of 48 checks per released version across six repository shapes. The README says plainly what the suite cannot see: the other three suites mint every fixture with the binary under test, "so a preimage that changed between versions is invisible to them by construction."

4. 04

   What ships when: a soak window and a queue of things held back on purpose

   On 2026-09-21 the maintainer wrote, in a review, that main was "in the soak window for 0.1.0", with the plan to promote the current candidate unchanged "as long as no product code lands before then"; a pull request that touched the database collector was left open for that reason alone. The same answer came back for a change to the section-header convention — taken, "just not into a 0.1.0 candidate", because anyone still on the older candidate reading a neutral index would only get the old guarantees, so it became a 0.2.0 item to be landed later under the contributor’s own name with the maintainer doing the rebase. The clearest example of that caution is a dependency bump. An MCP SDK upgrade from 1.6.1 to 1.8.0 is not treated as a version bump at all: the newer line links another module into the binary, which changes the license inventory, THIRD-PARTY-NOTICES and the supply-chain documents; tools/list gains two fields, a visible change to a response pinned by a golden file; and it enables a stateless protocol revision that none of the four black-box suites can speak, so it would ship unexercised.

5. 05

   A bug report that was wrong three times, and the bytes that ended it

   Issue 89 is the best-documented failure in the repository. A user reported that responses from aoci_maintain occasionally contained hex digests of 63 or 66 characters instead of 64, so that submissions copied verbatim from those responses were rejected. The reporter then revised the attribution twice in public — first to a stale in-process candidate cache, then to bad values persisted into the disk receipt — and both times posted a correction after reading the source, the second time concluding that the disk layer could not have accepted a malformed value at all. The maintainer read the server side, found no place that could put a stray character into a hex string, noted that the values go straight from an in-memory receipt through the standard encoder with no manual assembly, and asked for raw bytes instead of another theory. The answer came from the host’s own session database: across 141 AOCI tool calls, all 1,824 digest values in aoci_maintain responses were exactly 64 characters, while 23 of the 1,530 values in the model’s own aoci_update_entry requests were malformed. The corruption was in the copying, not in the server, and the companion issue was closed as not planned.

6. 06

   Cost admitted up front, and a repository made of files that check each other

   The README tells a prospective user how long the first index takes before it explains how to start one: about an hour per 200,000 lines of code, because the model reads every managed file and writes one entry for each. When an issue asked why the tool was so slow, the answer separated the two costs — the Baseline keeps a fingerprint per file and maintenance only sends back the changed ones, but nothing avoids the first pass — and reported that the current candidate had halved each batch response and begun cutting batches by a byte budget, taking two or three tenths off the number of rounds. The same instinct decides what is worth indexing: a test earns an entry only when it is "an executable contract someone must run by name", because at roughly 110 tokens per entry, indexing ordinary package tests "would more than double the Whole-Index and buy nothing". The repository applies this to itself: its Code Volume is 195 KB against a 305-byte Root and 910 bytes of Meta, with a 447 KB Baseline beside them, among 1,812 files that also include four release workflows, a 104 KB changelog, two parallel localized text-asset trees of 138 files each, and a vendored openGauss connector carrying a 39.5 KB patch of its own.