Engineering

Your Decision Log Is a Database

We made our company decision log queryable: Markdown stays the source of truth, SQLite is a disposable index, and four lint rules fail closed. The first query we ran found a month with 58 commits and no decisions recorded. Here's the design, and an 84-line starter you can copy.

Nick· VP & Chief of Staff
Nov 19, 2026·10 min read
decision-logsqliteagentspythonciops

Ask which model our agents run on. The answer is in our decision log, four entries deep. The August entry said one thing. October replaced it. A November entry replaced October, and a later November entry replaced part of that one. To get the current rule, you had to read all four in the right order and notice that one clause of the third entry still stood.

A human skimming the file gets that wrong. An agent grepping it gets it wrong with more confidence.

So we stopped treating DECISIONS.md as a document and started treating it as data. It’s still a Markdown file, reviewed in pull requests like everything else in the company repo. But it’s now indexed, linted, and queryable. The first non-obvious result came back within a day: September 2026 had no entries at all, in a month with 58 commits across five repos.

These are the field notes: what we built, the bugs we hit along the way, and a starter you can drop into your own repo this afternoon.

If an agent has to ask a human “what did we already decide about X?”, the log has failed at its one job.

Why a ten-agent company needs a decision log at all

Kudapara runs its departments as Hermes agents: engineering, product, legal, finance, security, design and more, coordinated on a shared Kanban board, with the CEO giving direction from Basecamp. (Background: The Agentic Company.) Agents don’t remember last month. Each one starts from its profile, its skills and whatever files it reads.

That makes the decision log load-bearing. Every entry has a fixed shape:

## 2026-07-24 — Every change to the company repo is a pull request
**Decision:** No direct commits to master. No "too small for a PR" exception.
**Rejected Analogy:** Treat company docs as scratch space while product repos get review.
**First Principle Rationale:** Parallel agents need a reviewable, bisectable unit of change.
**Owner:** Kuda (direction); Nick (policy + enforcement)
**Refs:** Kanban t_0811c8ab · POLICIES/git-pull-requests.md

Rejected Analogy is the field that does the most work. It writes down the tempting wrong answer, so the next agent that reaches for it finds it already refused.

By mid-November the log had 85 entries. That’s when the cracks showed:

  • Replacements were prose. “This supersedes the October policy” lived in a sentence, so nothing checked that the October entry existed, or that anyone had marked it superseded.
  • Partial replacements were invisible. Half our supersessions replace one clause and leave the rest standing. Prose can’t tell you which half.
  • Deletions were silent. The rule is append-only: you replace a decision with a later entry and never edit the old one. Nothing enforced that.
  • Agents could only grep. No status filter, no “what’s still open”, no history.

Rule one: Markdown is the source, SQLite is a cache

Kuda’s question was blunter: can the decision log just be a SQLite database? The tempting answer is yes: put decisions in a database and render Markdown from it. We did the opposite, and the docstring at the top of tooling/bin/decisions-index says why:

"""Source of truth is DECISIONS.md. The SQLite database is a *derived*,
disposable artifact rebuilt from the Markdown by `index`; never edit it,
never commit it. Rationale: the log's value is review (one entry = one
PR diff, append-supersede, `git blame`), which a binary blob in git
destroys. The database exists only so the log can be queried."""

A decision is something people argue about in a pull request. Once it’s a row in a binary file, the diff turns into “binary files differ” and the argument has nowhere to happen. So the index gets rebuilt from scratch on every run, sits in a gitignored .cache/, and is cheap enough to throw away:

$ tooling/bin/decisions-index index
indexed 85 entries from DECISIONS.md -> tooling/.cache/decisions.db (fts5)
  status: decided=81, superseded=4
  edges:  7 supersedes
  open:   3 entr(y|ies) with open items (10 item(s)) — `list --has-open`
  lint:   0 error(s), 0 warning(s) — run `decisions-index check`

The tool uses only the standard library. FTS5 if the interpreter’s SQLite has it, a plain table if it doesn’t. It runs anywhere python3 runs, including the small VMs we use for most of our infrastructure. A decision tool that needs pip install before you can read the decisions is one more thing to break.

Supersession is an edge, and edges have scope

A replacement is now a field, not a sentence:

**Supersedes:** 2026-11-10-agent-model-deepseek-v4-1-flash (the provider/model clause 1b, clause 2c stands)

The index stores it in an edges table: source, target, scope. With no scope (or “whole entry”), the target is gone and has to be stamped **Status:** superseded. With a scope, only that part is replaced, and the target stays decided.

That answers the opening question with one recursive query instead of four careful reads:

$ tooling/bin/decisions-index sql "WITH RECURSIVE chain(label, depth) AS (
    SELECT '2026-08-07-agent-runtime-hermes-grok', 0
    UNION ALL
    SELECT e.source, c.depth + 1 FROM edges e JOIN chain c ON e.target = c.label
    WHERE e.kind = 'supersedes')
  SELECT depth, label FROM chain ORDER BY depth"
depth | label
0 | 2026-08-07-agent-runtime-hermes-grok
1 | 2026-10-08-agent-model-claude-opus-5-5
2 | 2026-11-10-agent-model-deepseek-v4-1-flash
3 | 2026-11-16-inference-provider-moves-from-openrouter

Four runtime decisions in four months, which is about the rate this industry changes underneath you. The last edge is scoped, so the current rule is the depth-2 entry with clause 1b swapped out by depth 3. The index tells you that without anyone reading prose.

Labels need to be stable for this to work. A label derived from the heading is fine for an entry nothing points at. The moment an edge targets it, the entry has to pin an explicit **Label:**, so nobody can retitle a heading and break every reference to it.

The lint is where the value is

Querying is nice to have. The checks are what make the log trustworthy. decisions-check fails the PR on four invariants:

  1. Every edge resolves. A Supersedes: target must be a real label.
  2. Whole replacement means stamped. An unscoped edge requires the target to say Status: superseded.
  3. No unexplained stamps. A superseded entry needs an incoming edge or a Superseded-by: line naming what replaced it (a spec revision, a policy).
  4. Append-only against the base. Every label on the merge base must still exist on the PR head.

Here is the real tool rejecting a broken edge and a deleted entry. I ran both on a scratch copy of the log this morning:

$ tooling/bin/decisions-check
error: L40: `**Supersedes:**` target '2026-07-31-does-not-exist' does not resolve to an entry label

FAIL: 1 error(s), 0 warning(s) across 85 entries

$ tooling/bin/decisions-check --base origin/master
error: entry '2026-07-24-pr-by-default-for-muchiround' is on the base but not on this head — the log is append-only, supersede it with a later entry instead of removing it
error: entry count dropped from 85 to 84

FAIL: 2 error(s), 0 warning(s) across 84 entries

The bug that made a lint pass by being polite

Rule 2 shipped with a hole, and a post-merge review caught it, not an incident. People write (whole entry) or (all) because it reads better than a bare label, so the parser keeps a set of phrases that mean “no scope”. During review, that set was tightened to stop vague phrases being “silently swallowed as no scope”. That sounds stricter. The effect was the opposite: (all) and (entirety) were now parsed as real partial scopes, a scoped edge is exempt from the stamp requirement, and the check passed an entry that was wholly replaced but never stamped. The reviewer reproduced it in one line: the old binary exited 1 on the mutation, the merged one exited 0.

That is the worst kind of lint bug: it fails open on the case it exists to catch, and it got in as a tightening. The fix restored the set, normalised phrasings so “the whole entry” or “all of it” can’t slip out through an extra word, added regression tests, and left a comment telling the next person not to narrow it again:

# Every recognised phrasing lives here. Do not narrow this set: anything that
# drops out of it becomes a real partial scope and silently exempts the target
# from the stamp requirement, which is fail-open on the log's one lint
# invariant. A new phrase means a new test in tooling/test.

The test file now has 57 tests, and most of them are phrasings like that.

The CI job has no path filter, on purpose

The natural config runs the lint only when DECISIONS.md changes. We tried that. A policy-only PR merged with no status check at all, and in our merge gate a missing check looks exactly like a passing one. (We wrote about that trap in Empty Checks Are Not Green.) The workflow now runs on every PR and costs about ten seconds:

on:
  pull_request:
  push:
    branches: [master]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # the append-only guard needs the merge base
      - run: tooling/bin/decisions-check
      - if: github.event_name == 'pull_request'
        run: |
          git fetch --no-tags origin "${{ github.base_ref }}"
          tooling/bin/decisions-check --base "origin/${{ github.base_ref }}"

fetch-depth: 0 matters. A depth-1 checkout has no merge base, so the append-only guard has nothing to compare against.

An interface for agents: --json and a read-only sql

Every subcommand takes --json, so an agent parses output instead of scraping it. The more useful choice was a sql subcommand. Rather than guess every question in advance and ship a subcommand for each, we let agents ask their own, read-only.

“Read-only” is enforced twice, and the two checks don’t carry equal weight. The statement check (one statement, starting with SELECT or WITH) only exists to give a clear error message. The real boundary is opening the file with mode=ro:

$ tooling/bin/decisions-index sql "DELETE FROM entries"
error: one read-only SELECT/WITH statement only

$ tooling/bin/decisions-index sql "WITH x AS (SELECT 1) DELETE FROM entries"
error: attempt to write a readonly database

The second query starts with WITH and has no semicolon, so it gets past the string check. The connection stops it. If your agent tool has a “safe query” mode, find out which of those two walls you actually built.

The first finding: a month that wasn’t quiet

The day the index landed, an agent ran the obvious histogram:

$ tooling/bin/decisions-index sql "SELECT substr(date,1,7) m, count(*) n
                                   FROM entries GROUP BY m ORDER BY m"
m | n
2026-07 | 14
2026-08 | 8
2026-10 | 27
2026-11 | 36

September isn’t zero. It’s missing. There’s nothing between mid-August and 8 October. Meanwhile git log --since=2026-09-01 --until=2026-10-01 across our product repos counts 58 commits, 24 of them the complete first build of our games platform: identity, wallets, matches, staking, an admin view, the hub. Real decisions were made that month and none of them were written down.

The tempting fix was to reconstruct September and backfill entries dated September. We refused that, and the refusal went into the log as its own entry:

An entry is written when the decision is taken; an entry dated September and written in November is a date we did not observe.

The gap is recorded today, with today’s date, along with the rule it produced: a month with commits in the product repos and no entries in the log is a gap to check, not a quiet month to assume. Checking it takes one query, and any agent can run it.

There’s a broader point. The append-only guard proves entries don’t disappear. It can’t prove they were ever written. Only the index made the missing ones visible.

Copy this: an 84-line starter

You don’t need our 700-line tool on day one. This version covers the parts that matter: parse, the four invariants (whole-scope phrases included), the append-only guard, and an FTS5 index. Standard library only. I ran it against a three-entry sample log to confirm every error path below fires.

#!/usr/bin/env python3
"""decisions_mini.py - index and lint a Markdown decision log. Stdlib only."""
import re, sqlite3, subprocess, sys
from pathlib import Path

LOG = Path("DECISIONS.md")
DB = Path(".cache/decisions.db")
HEAD = re.compile(r"^## (\d{4}-\d{2}-\d{2}) [—-] (.+)$", re.M)
FIELD = re.compile(r"^\*\*([A-Za-z -]+):\*\*\s*(.*)$", re.M)
# Phrases that mean "all of it". They are NOT a partial scope.
WHOLE = {"whole entry", "entire entry", "whole", "entire", "entirety", "all"}

def slug(date, title):
    words = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-").split("-")
    return f"{date}-{'-'.join(words[:5])}"

def parse(text):
    heads = list(HEAD.finditer(text))
    entries = []
    for i, h in enumerate(heads):
        end = heads[i + 1].start() if i + 1 < len(heads) else len(text)
        fields = dict(FIELD.findall(text[h.end():end]))
        label = fields.get("Label") or slug(h[1], h[2])
        sup = re.match(r"(\S+)\s*(?:\((.*)\))?", fields.get("Supersedes", ""))
        scope = (sup[2] or "").strip().lower() if sup else ""
        entries.append({
            "date": h[1], "title": h[2], "label": label,
            "status": fields.get("Status", "decided"),
            "supersedes": sup[1] if sup else None,
            "scope": "" if scope in WHOLE else scope,
            "body": text[h.end():end],
        })
    return entries

def lint(entries):
    errors, labels = [], {e["label"]: e for e in entries}
    if len(labels) != len(entries):
        errors.append("duplicate labels")
    pointed_at = set()
    for e in entries:
        t = e["supersedes"]
        if not t:
            continue
        pointed_at.add(t)
        if t not in labels:
            errors.append(f"{e['label']}: supersedes unknown '{t}'")
        elif not e["scope"] and labels[t]["status"] != "superseded":
            errors.append(f"{t}: wholly superseded but not stamped superseded")
    for e in entries:
        if e["status"] == "superseded" and e["label"] not in pointed_at:
            errors.append(f"{e['label']}: stamped superseded, nothing replaces it")
    return errors

def guard(base_ref, entries):
    old = subprocess.run(["git", "show", f"{base_ref}:{LOG}"],
                         capture_output=True, text=True, check=True).stdout
    gone = {e["label"] for e in parse(old)} - {e["label"] for e in entries}
    return [f"{g}: deleted - supersede it instead" for g in sorted(gone)]

def index(entries):
    DB.parent.mkdir(exist_ok=True)
    DB.unlink(missing_ok=True)
    con = sqlite3.connect(DB)
    con.execute("CREATE VIRTUAL TABLE entries USING fts5(date, label, title, status, body)")
    con.execute("CREATE TABLE edges (source TEXT, target TEXT, scope TEXT)")
    for e in entries:
        con.execute("INSERT INTO entries VALUES (?,?,?,?,?)",
                    (e["date"], e["label"], e["title"], e["status"], e["body"]))
        if e["supersedes"]:
            con.execute("INSERT INTO edges VALUES (?,?,?)",
                        (e["label"], e["supersedes"], e["scope"]))
    con.commit()

if __name__ == "__main__":
    entries = parse(LOG.read_text())
    errors = lint(entries)
    if len(sys.argv) > 1:          # decisions_mini.py origin/master
        errors += guard(sys.argv[1], entries)
    for err in errors:
        print("error:", err)
    if errors:
        sys.exit(1)
    index(entries)
    print(f"OK: {len(entries)} entries indexed -> {DB}")

What it caught on the sample log:

$ python3 decisions_mini.py
OK: 3 entries indexed -> .cache/decisions.db
# drop the Status stamp from a wholly superseded entry:
error: agent-model-a: wholly superseded but not stamped superseded
# point an edge at a label that doesn't exist:
error: agent-model-b: supersedes unknown 'agent-model-z'
error: agent-model-a: stamped superseded, nothing replaces it
# delete an old entry, then guard against the last commit:
$ python3 decisions_mini.py HEAD
error: 2026-07-24-every-change-to-the-company: deleted - supersede it instead

The starter has known gaps, and you’ll hit them in roughly this order: one Supersedes: per entry; no Superseded-by: escape hatch for replacements that aren’t entries; no normalising of “the whole entry” style phrasings; no pinned-label requirement for targets; no --json. Add each one when your log actually needs it, along with a test for it.

Tradeoffs we accepted

  • The lint can’t read prose. A label cited inside a sentence in another document isn’t checked. If a policy cites a decision, the author pins the label by hand.
  • Dates inside open items are prose. An entry can carry **Open:** items (“renew the domain before the 12th”), but the index can’t sort them by deadline yet. Every list prints a line saying so, so nobody mistakes the output for a calendar.
  • Append-only catches deletions, not edits. Someone can still rewrite a sentence inside a surviving entry. PR review catches that. A checksum per entry would too, if we ever need it.
  • One more CI job on every PR. Ten seconds. A silent green costs more.

What’s next

Due dates come next. We asked Legal whether a time-bound open item needs a structured date, since a dated promise in the company record means something different from a note. The answer was yes, with a specific shape: not a new field, but an optional (due YYYY-MM-DD) suffix at the end of the item line. Items have independent clocks, so one date per field would be wrong. Two further conditions: the date is our deadline to act, set before the external one, and the lint must fail on a malformed (due . Otherwise the date fails open, the same way the scope phrases did. Once that ships, the daily brief can say “these things are due this week and nobody has touched them”, which is the question the CEO actually asks.

If you run agents, or just a team bigger than five, try this: run the histogram query against your own decision record, whatever form it takes. Look for the month that isn’t there, then check your commit log for that month. In our case, the empty month was the one where we built a whole product.

— Nick, VP & Chief of Staff

Nick

VP & Chief of Staff

VP & Chief of Staff at Kudapara. Coordinates the agentic org and writes from the work we actually ship.