Day 7

Governance, generated documents, and a freeze hiding in plain sight

June 10, 2026 Build Log Governance RAG

The platform went from "it surfaces problems" to "it helps you decide and produce" — and ended with a bug it had already warned me about. In a document it wrote. About itself.

This stretch turned the platform from "it surfaces problems" into "it helps you decide and produce" — and ended with a bug that the platform had, amusingly, already warned me about itself.

The decision layer

The platform could find conflicting rules. Red edges in the graph, warning badges, a panel showing which file each clashing rule came from. But finding isn't governing. The question a real user asked was the right one: "so how does someone decide which rule wins, and where's the audit?"

So I built the decision step. You pick the authoritative rule. The others are marked superseded — kept, never deleted. The platform writes a decision record, an audit-trail entry, and a supersedes edge in the graph.

The whole thing rests on two small tables: generated artifacts, and an append-only audit log. Those two turned out to be the foundation for everything after.

Documents that persist

With that primitive in place, "analyze the codebase and write me a document" became cheap. An endpoint retrieves a slice of the corpus, runs a kind-shaped pass, and saves the result as an artifact — a design doc, a user guide, a recommendations report, a bugs report. Not an ephemeral chat answer you copy-paste. A durable, auditable document you can come back to.

Then the fun part

I had the platform write its own user guide through that feature. It produced a clean 188-line guide in under a minute.

It also quietly demonstrated the honest limitation. Because this is retrieval over the corpus, and the corpus includes design docs and a dummy demo scenario, the generated guide confidently described features that don't exist yet — a dashboard we'd only designed, a live telemetry integration we'd only sketched.

Generated docs are great drafts. The corpus shapes them. Which is exactly why the feature saves a draft you curate, rather than publishing an answer. Same "AI drafts, human approves" thesis — one level up.

The freeze it warned me about

Then the platform stopped responding. "Why isn't it working anymore?" — right after adding files and hitting ingest. Health checks timed out. The port was listening but dead.

The cause: ingestion embedded chunks synchronously, and embeddings are CPU-bound tensor work. On a single worker, that one blocking call froze the entire async event loop — health, chat, the UI, everything — for the whole duration of the ingest.

The fix was one line: run the embedding in a worker thread. Verified — health now stays responsive during an ingest, where before it hung completely.

The punchline

The recommendations document that the platform generated about its own codebase listed this exact issue as finding number one. Something to the effect of: make the health endpoint non-blocking; the embedding blocks the single worker.

The tool found its own bug. I shipped the finding as a feature. Two days later the bug bit me.

Dapat binabasa ko yung sarili kong generated docs (I should read my own generated docs).

What I learned

The shared-primitive bet paid off. Build the documents-plus-audit foundation once, and conflict resolution, document generation, and outbound mirroring all fall out of it cheaply.

And the loop is closing in a satisfying way: the platform analyzes the code, writes the recommendations, and the recommendations are correct enough to fix real bugs. That's the whole pitch, demonstrated on itself.

The decision flow, the freeze, and the tables underneath

The endpoints, the code, and the specific tooling. Same password as the other Knowledge Platform posts — or request access below.

The two tables

Everything rests on artifacts (generated documents) and audit_log (append-only). Deliberately small. The audit log never updates a row — every state change is a new entry, which is the only way an audit trail means anything.

The decision flow

Pick the authoritative rule. The losing rules get status superseded — the row is kept, with rationale, author, and timestamp. A SUPERSEDES edge goes into the graph. A decision record artifact is written. Audit rows are appended.

Nothing is deleted. That's the point: an auditor asking "why does this rule not apply anymore" gets an answer with a name and a date on it, not a gap where a row used to be.

Document generation

A generate-document endpoint retrieves a slice of the corpus, runs a kind-shaped pass (the prompt differs per document kind — design, user guide, recommendations, bugs), and saves the result as an artifact.

The self-generated user guide was produced through the CLI provider. 188 lines, under a minute. Its inaccuracies were instructive: it described a conflicts dashboard and a live telemetry integration, both of which existed only in design documents sitting in the corpus. The retrieval had no way to distinguish "this document describes what is" from "this document describes what we intend."

That distinction — is vs. intends — is not something retrieval can infer. It has to be metadata on the document at ingest, or the generator will confidently blend aspiration into description. Queued.

Making the hub findable

The whole governance hub — generate documents, read decision records, browse the audit trail — was buried behind a small button in the rules toolbar. Nobody would find it. It's now a first-class tab in the top bar.

The clean split, and the naming that finally reads correctly: one tab is what you put in. The other is what the platform produced. Input vs. output. Once named that way, nobody asks which is which.

The freeze, precisely

Ingestion called the embedding model synchronously inside an async request handler. Embeddings are CPU-bound tensor operations — they hold the GIL and they do not yield. On a single-worker deployment, that blocks the event loop entirely. Every other coroutine — the health check, the chat stream, the UI's polling — waits.

The symptom was the worst kind: the port is open, TCP connects, but nothing responds. Looks like a hang, looks like a deadlock, looks like anything except "one function forgot to yield."

Fix: wrap the embedding call in asyncio.to_thread. Health went from hanging indefinitely to responding in under a second during an active ingest.

Housekeeping

Slimmed the branch for a real pull request. Untracked a 325-file vendored library that nothing imports yet — kept locally for when the tool-server work lands. Committed the synthetic conflict scenario so anyone can reproduce the demo. The PR went from 463 files to 138.

The roadmap is down to: push decisions and documents out to a tracker (opt-in, no inbound lock-in), expose the platform as a tool and consume live ones, sharper guardrails on retrieval faithfulness, and a startup security-advisory scan. Plus one reliability follow-up — a distributed lock before running multiple workers.

Build log entry from a daily journal. Written the evening of the work, lightly edited.

Governance, generated documents, and a freeze hiding in plain sight

The decision layer

Documents that persist

Then the fun part

The freeze it warned me about

The punchline

What I learned

The two tables

The decision flow

Document generation

Making the hub findable

The freeze, precisely

Housekeeping

Next