The Reading Oath
Make an AI prove it read your whole codebase instead of confidently skimming it.
The ingredients 5 gifts
Pick your depth — take the quick way in, the full walk-through, or the deep build. Same recipe, your call today.
Quick you want an AI to stop bluffing about your codebase
The move: break the repo into shards, make the model answer per-shard, and reject any claim that doesn't point at a byte-derived fact. Coverage becomes checkable; confident skimming stops passing.
Start small — one repo, the claim-check loop, a hard rule that an unsupported claim doesn't enter the answer.
facts = cruise(repo) # byte-derived fact ledger
claims = ask_model(excavation.shards(repo))# per-shard, collect claims
answer = [c for c in claims if c.points_at(facts)] # unsupported -> dropped
assert every(c.has_evidence for c in answer), 'a claim slipped in unsupported'Working you want to understand how coverage becomes checkable
The five parts below walk it: excavation shards the repo, the harness feeds shards to the model and collects claims, cruise supplies a fact ledger, and each claim is checked against it before it's allowed into the answer.
The prompt engineering here is small — the discipline is in the check, not the prompt.
Deep you want to know the honest bound
cruise is a pattern scan, not a language parser — a framework idiom it wasn't taught is a fact it won't see. Crucially it fails SAFE: it omits a real fact, it never fabricates one. So a clean cruise run means 'look here,' not 'nothing here.'
You are bounding the AI's confidence to what's provable, not achieving omniscience. That's the whole value — and pretending otherwise would rebuild the bluffing problem one level up.
For real use: treat an unsupported-but-plausible claim as a prompt to EXTEND cruise's coverage, not to relax the gate.
The idea
The failure you know: paste a repo at an LLM, ask 'any security issues,' get an authoritative answer from a model that actually looked at 3 files. This composition makes that structurally hard — coverage becomes a checkable property, and every model claim has to point at a byte-derived fact before it's allowed into the answer.
The parts + how they wire
excavation enumerates your site/corpus as typed nodes and shards it by budget, then tracks coverage against that enumerated oracle until the set-difference is empty. cruise walks the code and emits only byte-derived facts, each carrying what it proves and what it does not. verify keeps a content-hash certificate so re-checking 'did I read this' is a one-second FRESH/STALE/DEAD. ward badges the reading green only when the coverage witness agrees. markdown renders the oath as HTML + verbatim plaintext from one AST so the human and machine views can't drift.
The one piece you build
The prompt harness — the loop that feeds excavation's shards to your model, collects claims, and checks each claim against cruise's fact ledger before letting it into the answer. That's the actual prompt engineering here, and it's small.
The technical breakdown
excavation makes coverage a checkable property, not a vibe: it builds a manifest (every page/file as a typed node — the coverage oracle), shards (context-sized chunks), and a coverage tracker that does set-difference against the manifest until nothing remains. Your harness loops pull-shard → feed-model → mark-covered until the difference is empty; 'I read all of it' is a set operation, not a claim. cruise gives the anti-hallucination oracle: each fact is a route (a server path literal in a handler), an affordance (a user-visible control label), or a claim (a test-file assertion), and every fact ships its own proves and does_not_prove — a route fact proves a path literal exists, not that the route works or is tested. Your harness rejects any model claim that can't point at a matching cruise fact. verify's FRESH/STALE/DEAD is the incremental layer: on a re-read you don't re-feed shards whose certificate still hashes FRESH, which makes the oath cheap to re-take after a small change.
The honest edge
cruise is a pattern scan, not a language parser — a framework idiom it wasn't taught is a fact it won't see. It fails safe (a real fact omitted, never a fabricated one added), so a clean cruise run means 'look here,' not 'nothing here.' You're bounding the AI's confidence to what's provable, not achieving omniscience.
These are ingredients, not instructions you have to follow. Take these parts and cook something — the recipe as written, a variation, or something we'd never have thought of.
Built it, got stuck, or found a mistake? Shea wants to hear it — success stories, questions, and bug reports all land in the same inbox: