Technical log
architecture · sheet 1 of 1
Cairn is a log book for your codebase. Your coding agent writes down what each part is meant to do and why. Wire Cairn into your commit hook. On every commit it compares what you declared with the real code. The serious disagreements fail the commit before they go any further.
Comparing a written record against the real thing is called reconciling. A mechanic does it before an aircraft may fly. Do it to a codebase, and the notes you leave today are still worth trusting a year from now.
The middle column is the check itself, drawn as a mark borrowed from the workshop. A mechanic paints one line across a bolt and its housing, so that later a single glance shows whether the bolt has turned. Here the line is painted across what you declared and what is on disk. While the two halves meet, the records agree. When they slip apart, that is drift.
Each entry below is complete as it stands. Open one to see the file, the command, or the output behind it.
This passage from Cairn's own blueprint omits only the marked cuts. Each node claims its paths, names the contract it must honour, and inherits the decisions that constrain it. Every line can be checked against the files it describes.
# Cairn, the framework described as a Cairn project. System Cairn "Architecture map framework with pluggable reconcilers" id "cairn" @framework { decisions "./meta/decisions" research "./meta/research" todos "./meta/todos" ... Module State "Pluggable state persistence backend" id "cairn.state" { path "./src/state" contract "./meta/contracts/state.md" } Module Watch "Watch mode: periodic scan with finding-change events" id "cairn.watch" { path "./src/watch.rs" contract "./meta/contracts/watch.md" } ... }
cairn init --from-code --apply --wire
Wire cairn hook all into pre-commit or CI and it becomes the gate. It holds you to what you have actually written down, so it stays quiet until you write a promise worth keeping. Below is real output from this repository on 27 July 2026, with the JSON wrapped to fit.
$ cairn hook all Hook: all Decision: pass Elapsed: 12ms Findings: 1 deferred finding deferred by dec.revisit-trigger-correlator-deferred $ cairn lint --json {"findings":[{"code":"CAIRN_SPEC_RULE_UNIMPLEMENTED", "message":"spec rule `ADR revisit_triggers appear relevant to recent changes` (spec:634) is pending but names no enforcer (deferred by dec.revisit-trigger-correlator-deferred)","node":null, "path":"docs/registries/spec-rules.md","severity":"info"}], "schema_version":4}
This output is real, with five accepted decisions cut for length. One command returns the node's dependency edges and its owning contract. It also returns every accepted decision that binds the node, including the ones that reach it via its neighbours.
Node: cairn.reconcile Inbound: - cairn.kernel.scanner Outbound: - cairn.kernel.map Contracts: - ./meta/contracts/reconcile.md Accepted decisions: - dec.claim-only-assets-targets [accepted] cairn.kernel.scanner, cairn.ui - dec.code-reconciliation [accepted] cairn.reconcile - dec.contract-leaf-coverage [accepted] cairn.kernel.map - dec.domain-expandability [accepted] cairn.root, cairn.reconcile - dec.order-containment-rule [accepted] cairn.kernel.query, cairn.kernel.map - dec.graph-root-fingerprint [accepted] cairn.kernel.scanner, cairn.reconcile ... 5 more
In a workshop, a red tag keeps an aircraft on the ground until a mechanic clears the fault. An amber one lets it fly and books the repair. When everything is called a warning instead, everything gets waved through, and a good plan rots quietly.
Two of those tags are red, and once the gate is wired both fail the commit. They are kept apart because you clear them in different ways. A broken record has to be repaired before anything else it says means much. A contract the code has outgrown is settled by updating the contract and recording the new hash, or by putting the code back. One shared word for both would tell you that something is wrong and leave you to guess what to do about it.
Cairn declares itself in its own cairn.blueprint and checks itself against its own source on every commit. The numbers below were read from the graph on 27 July 2026. They move as the repository moves, so clone it and run cairn context to see today's.
Cairn (25 nodes, 27 edges) Architecture map framework with pluggable reconcilers Findings: 0 errors, 0 warnings, 1 info Structure: cairn brownfield -> kernel # Reads orphan findings kernel (8 nested node(s) collapsed; cairn context --scope kernel) -> brownfield # Dispatches onboard command -> reconcile # Invokes registered reconcilers -> state # Reads beads to flag orphan node labels -> ui # Launches graph explorer mcp -> kernel # Wraps queries as MCP tools reconcile -> kernel # Reports findings to graph state ui -> kernel # Runs scans for API responses; Serves graph data -> state # Reads node-linked beads for the inspector ... 10 more nodes Artefacts: 22 contracts, 81 decisions, 134 todos, 25 research, 14 sources
The one finding left is an info: a spec rule that nothing enforces yet, put off on purpose by a recorded decision. It stays in the log, in plain sight, with the reason written beside it for whoever reads next.
A chain of paper shows why an aircraft may fly. A signed certificate turns that evidence into permission. Cairn is built the same way. This is the record that answers "why is it like this" when you come back a year later and cannot remember.
The raw material: a paper, a benchmark, a chat thread, a spec you had to read.
What you made of it, with its sources cited, so anyone can walk the reasoning again.
It reads the evidence and it issues the rule. When you ask why a part is shaped this way, this is the record that answers.
dec.code-reconciliationThe shape of the system: which parts exist, and how they depend on each other.
The promise a part makes to everything built on top of it.
What is actually on disk. This is the reality the record is measured against.
Ask any node why it is shaped the way it is, and you get the trail back. cairn rationale cairn.reconcile returns every accepted decision that binds it, with the research and the sources in its rationale chain. The argument your team had in a thread six months ago ends up beside the code it shaped.
A reconciler answers one question: for a part you declared, what is really there? The source-code reconciler is the only one certified today. Cairn's core works with any of them, so the same machine applies wherever a written record has to stay honest with reality.
Your first scan writes map.md and map.json, so a person reading a diff can see the shape change. From the next prompt on, your agents get their bearings from three commands: cairn context, cairn get, and cairn neighbourhood. That saves them reading your whole source tree again to work out where they are. Everything runs on your machine.
Read https://raw.githubusercontent.com/cairn-framework/cairn/main/docs/agent-setup.md and follow it to set up Cairn in this repo.
Your agent installs the CLI, works out whether this is a new or an existing project, drafts the blueprint with you, wires itself in, and arms the gate.
$ curl --proto '=https' --tlsv1.2 -LsSf \ https://github.com/cairn-framework/cairn/releases/latest/download/cairn-installer.sh | sh $ cairn init --wire # scaffold, install the agent pack, wire it in $ cairn scan # reconcile, write the map $ cairn hook all # the gate: wire into pre-commit or CI
Leaving is a short job. Try it on a branch. If you hate it, run cairn pack uninstall, which retires the pack files Cairn owns and has not seen edited. Delete any pack file you did edit yourself. Then delete cairn.blueprint, cairn.config.yaml, .cairn/, the generated map files, and the empty meta/ folders the scaffold made. Last, take Cairn's block back out of your agent instructions file, or delete that file if Cairn created it. Already have a codebase? cairn init --from-code drafts the whole blueprint from your source tree as a change proposal you review before anything lands.