Library re-do: an engineered knowledge base for a working AI

Project 30: rebuilding my lab’s documentation into a retrieval-ready knowledge base, and applying the same cleanup discipline to the lab’s code.

knowledge-base engineering RAG readiness evaluation discipline currency enforcement AST-gated apply

The local AI kept failing in ways that traced back to a messy knowledge base. Dangling narrative commentary sat beside current procedure, stale claims were served as current because nothing enforced currency, and documents were too large for the retriever to handle well. The AI needed a clean library to work from.

I ran a two-part campaign in service of Project 12 (the self-engineering program), because the AI that program builds is only as good as the library it reads. The docs half rebuilt the library as an engineered knowledge base with enforced currency and automated succession tooling. The code half applied the same comment-cleanup criteria across the four code mirrors in my own lab fleet. Its pipeline ran detect, draft, review, then AST-gated apply, a parse check that blocks any edit that would not compile. This arc closed 2026-08-26, five days before the self-engineering program it served.

The knowledge base

Before this campaign the vault had no enforced currency, and retrieval broke on oversized pages. The goal was RAG readiness, which meant every change had to survive the retriever before it counted as done.

The currency gate is what makes this durable. A verify step refuses a restructure until every claim in the affected documents has been dispositioned as current, superseded, or retired. The cameras domain pilot proved the loop works. The documents confidently described a service that had been removed weeks earlier, and the gate caught it before anything shipped. The link audit at close: 621 wikilinks across the vault, 0 broken, with the archive excluded from resolution.

The succession tools are a gated family: propose and apply a split, carve a section at heading seams, draft an index page, probe retrieval, check inbound references, apply a restructure, apply wikilinks. A future consolidation can be driven by the local AI without a frontier model session. The extract/review/findings machinery built here also ran the reconnaissance passes for Native Intelligence (the thesis behind the whole program).

A written library charter governs how the documents behave. Two of its rules carry most of the weight. Findability is the acceptance test, meaning a stuck session searching the obvious term must land on the answer. And every file is either definitive or additive, and says which. Superseded content moves to an archive that stays outside retrieval scope, so a stale page cannot be served as current by accident.

The code cleanup pipeline

The same two-bar criteria from the docs half applied to code. A comment stays only if it states a true constraint the code cannot show on its own, and only if it is as sparse as a skilled human would write. War stories, dated blocks, doctrine citations, pasted quotes, and narrative commentary were candidates for removal or move.

The pipeline ran detect, draft, review, then AST-gated apply across four mirrors. The two large ones were the orchestrator (784 dispositions) and the training foundry (710); the shared lab tool library and the ARM cluster's head were smaller. A local 27B model drafted all 710 foundry rewrites. I adjudicated them using agent sessions as the review tool, rejected 26 outright, and hand-wrote 8 more the model kept getting wrong. Two independent review passes on consecutive days converged on the same judgments. Every suite went green, every consumer was redeployed, and the running code was verified after deploy.

The AST gate then found 13 malformed drafts among the rewrites that had already passed eyeball review. The catches were stray braces at the wrong nesting level, docstring quotes opened and never closed, and raw-string prefixes dropped from path strings so they broke on parse. One rewrite deleted the code line that followed it. Eyeball review catches judgment errors and only a parse gate catches formatting ones, so both are required.

What the pipeline taught

A green model draft is not an applyable draft, so a parse gate is required in any pipeline that touches source files.

Drafts drawn one day were applied the next over files that had changed in between. Because the pipeline matches byte-exact spans and re-scans fresh before every apply, every drifted row surfaced as an explicit refusal and was re-anchored by hand. Nothing misapplied silently. Line numbers do not identify a comment across even one day of drift.

The model drafted every rewrite and the judgment lived at the margin, on the rejects and the repeated failures, which is where a human review pays for itself.

One hand rewrite was wrong in a way the draft packet could not show, and it was caught only because the live code was read instead of the diff.

I rejected my own close because it still carried named residuals, and a same-night burn-down cleared every one. The final whole-tree audit re-scanned 378 source files across the four mirrors; 25 live detector hits remained, each an individually reviewed keep.

The library is rebuilt and the code mirrors are cleaner, and keeping the knowledge base current is ongoing work the succession tooling is built to carry as the lab grows. Retrieval was the acceptance criterion, but I never built a standing retrieval benchmark: the improvement was verified probe by probe at each restructure, not measured in aggregate. The currency gate runs when a restructure is proposed, and nothing re-verifies a document on a schedule, so a claim can still go stale between restructures.