0004 — How this ledger works: decisions die in conversation unless written here
- Status: Accepted
- Date: 2026-08-29
- Deciders: Gera (2026-08-29: "a lot of the time… the fact that you didn't know that we were dismissing Tmuxes… I don't want to just put it in our memory because then it can pollute it… we should be smarter than just like vibing through it").
The problem this file solves
The tmux→SendMessage decision (ADR-0002) was real, was Gera's, and existed nowhere a fresh session could find it — so a session built new tmux surface against it the same week. Agent memory is the wrong record: it is per-agent, unreviewed, and mixes behavioral calibration with doctrine.
The rule: a decision that changes how systems relate is not finished until its ADR is written here — at decision time, as part of deciding, not as aftercare. Whoever is in the room when the decision happens writes it.
Where things live (three tiers, no overlap)
| Tier | Contents | Reaches |
|---|---|---|
Per-repo CLAUDE.md / code comments |
repo-specific conventions and scars | sessions in that repo |
This ledger (agentflow/docs/adr/) + SYSTEMS.md |
cross-system decisions; the catalog | every session, via the global ~/.claude/CLAUDE.md pointer and docs.propflowai.co |
| Agent memory | one agent's calibration and continuity | that agent only — never architecture-of-record |
agentflow hosts the fleet ledger because it is the coordination layer and
ADR-0001 was already a fleet decision; a dedicated repo was considered and
rejected — a new location is more of the fragmentation disease, not a cure.
Status lifecycle
Proposed → Accepted → Superseded-by-NNNN → Removed.
A superseded ADR is never deleted (the reasoning stays valuable) and never merely relabeled. A superseding ADR must carry three parts or it is not done:
- the decision and what it replaces;
- an inventory of the old surface — the scripts, skills, memory entries,
and code paths that implement the superseded way (ADR-0002's table is the
model). The inventory is what was missing when tmux "was deleted
intentionally" yet
drive-send.sh, a skill mode, and an authorizing memory entry all survived; - removal or fencing, in the same effort — delete what can die; where
something must linger, a guard (the
guard-bash.shpattern) that flags reintroduction. This is the product codebase's existing "no legacy, total elimination" doctrine applied to agent infrastructure.
Liveness doctrine (the inert-mechanism clause)
A mechanism ships with its own production liveness proof. Tests prove the
rule; they cannot prove the rule is ever reached — the anti-herd picker ran
inert for weeks with green tests, and the reviewer-token rotator died every
2 hours for 13 hours with its only witness being itself. The proof is a
signals entry in SYSTEMS.md (rendered live on /agents?tab=Systems,
where unknown never renders healthy), or where that does not fit, an
external freshness check wired to the ops alarm ledger.
Rendering
These ADRs render on docs.propflowai.co through the same pipeline that
renders propflowai's product ADRs. Product decisions stay in
propflowai/docs/adr/; this ledger is for how the fleet's systems relate.