WHY #
Who this is for: human-agent teams #
closedtab is built for human-agent teams. A person and one or more AI agents do
work across a sprint, or a stack of sprints, and that work needs a memory the
whole team can carry: the human, the agent that did this segment, the agent that
picks up the next one, and the agent re-reading it three sprints later. These are
not human-human retrospectives; those exist and are a different thing. This is the
shared record a human-agent team leaves so the next tab opens where the last one
closed.
Start with the habit, not the audit #
closedtab is two things, in order of importance. First and foremost it helps the
team write these docs, because almost nobody does, and the practice is worth
more than any tool built on top of it. A doc is a two-minute note at the end of a
segment of work: what the owner asked, what the agent did, why it was done that
way, and the decisions worth remembering. Writing them is the whole point; the
structure and the guided prompts exist to lower the friction until it's a habit.
Two sections carry the human-agent signal. Decisions and follow-ups records
the deliberate choices and who made them, owner or agent or joint, which is the
thing a future agent most needs and most often lacks. For the next agent is
the breadcrumb trail: the open hooks left in the code, the gotchas burned in
during the build, and what not to touch. That is exactly how a good CLAUDE.md
reads, a list of deliberate calls labeled so nobody reverts them by accident.
The second thing, reconciliation, only makes sense once the first exists. It presupposes you have docs to check. If nobody writes them, an audit tool has no input. So authoring is the front door, and the rest of this document is about the audit layer you grow into later.
The audit layer: does the account match the run #
We delegate work to agents and then read their account of it. The account, the
After-Action Report, is written by the same actor whose work it describes. When
the account and the work diverge, nothing catches it. The agent that misremembers
"I left app.py untouched" while having written to app.py, or claims "the suite
passed" when no suite ran, produces testimony that reads exactly like testimony
that's true.
closedtab reconcile answers one question and only one: does the account of the
run match the run. It takes the testimony (the AAR) and a trace (a normalized
machine record of what actually happened) and reports the deltas. It is a
deviation logger for delegated agent work.
What it deliberately is not #
It does not score risk. It does not grade the agent. It does not decide whether a deviation was dangerous, acceptable, or worth escalating. Those are real and separate jobs; conflating them with reconciliation would make the reconciliation less trustworthy, because you'd be tempted to soften a contradiction to avoid a scary score. Here a contradiction is just a finding: flat, mechanical, logged. Judgment lives in other tools that can consume this diff.
That is also why a contradiction is not a CLI error. The tool succeeding means it produced the diff, not that the diff is clean.
Why deterministic, local, no LLM (in v0) #
The thing checking the agent's testimony shouldn't itself be an opaque generator
of plausible-sounding text. v0 matches claims to events with plain, readable
rules: an exact file path against a file_write target is a high-confidence
match; a substring is medium; a lone verb is low. An engineer can read
matchLevel() and see exactly why a claim matched an event. No network, no API
key, no nondeterminism.
An LLM-assisted matching mode is a sensible later addition for the fuzzy middle
(paraphrased claims, semantic equivalence). The code leaves a marked seam for it,
// v0 heuristic: LLM-assisted extraction plugs in here, behind the same
ExtractedClaim x TraceEvent interface, so it can be added without the
deterministic core losing its legibility.
Built against real AARs, not an idealized schema #
Real AARs use freeform, task-specific headers: "What bit me", "The fix", "Files touched", "Decisions and follow-ups", "TL;DR". So the parser is header-agnostic: it pulls claims from prose under whatever headings exist, and uses headings only as section-origin hints.
Three sections do real work in reconciliation, so they're detected by matching their naming variants:
- intent: the human's ask.
- claimed_actions: what the AAR says was done.
- negative_space: what was deliberately not done or deferred. The parser still recognizes the older "what I did not do" phrasing as well as the decisions-and-follow-ups framing, because both appear across real AARs, and a deferred follow-up is exactly the kind of claim worth checking against the run.
The variant lists weren't guessed. They were finalized from a heading-frequency
table built over the whole corpus (~280 aar-*.md files across two projects).
npm run corpus-report regenerates that table and writes unmapped-headings.json,
every heading the parser still files under "other". A heading that recurs there is
the signal to extend the lists. The recurring ones today (validation,
verification, tl;dr, why, context) are genuinely supporting prose, not
anchors, which is the parser showing it generalizes.
The anchors are exact identifiers #
Real AARs are dense with file paths (o27v2/web/app.py), line ranges
(1626-1648), commit hashes (b1787ef), PR numbers (#73), branch names, and
function names (_pick_decisions). Those identifiers are what make a claim
checkable against an event, so extracting them cleanly is the highest-value part
of the parser, and the most heavily tested, against real identifier strings
pulled from the corpus.
On the trace side #
The corpus gives us real testimony but no traces. So in v0 the testimony is
tested against real data while traces stay synthetic fixtures (examples/). The
fixtures are the spec: each is a testimony plus trace plus the exact diff the core
must produce. A vendor trace adapter, turning real agent logs into the canonical
TraceEvent shape, is the next milestone, after which the trace side gets the
same real-data treatment the testimony side already has.