Wednesday, May 21, start of session, coffee next to the keyboard. I ask the agent where we stand on the DEV.to series. Clean answer, articulated, "Four articles on stand-by, ready to publish." I reread. Half a second of unease, because I think I saw two or three of them go through DEV.to last week, but I slept in between and I'm no longer sure. I type the question that changes everything, "Are you sure articles remain to publish?" The agent re-queries the DEV.to API in parallel, opens scripts/devto/state.json
, crosses the two. The four articles have been published for two or three days.
What I just read wasn't a hallucination. The agent did exactly what was expected of it, namely open articles/backlog.md
, read the table, restitute what it said. I'm the one who had stopped updating that file. sync-backlog.ts
hadn't run after the pushes of last week. The markdown said "stand-by" while production said "published". The typist didn't lie. She read faithfully a file I had written myself and that I was treating as authority while nothing was maintaining it.
This is the most common failure mode of a solo project that lasts. Each day produces two flows. On one side the matter that moves, made of commits, deploys, rows in the database, statuses that transition. On the other side the writings we draft to keep our bearings, namely backlog.md
, the root MEMORY.md
, the Sunday-night session note, the README of the folder we refactored last week. These writings are produced quickly, in the gesture that closes a sprint, and they are maintained slowly, or not at all, because nothing in the pipeline triggers to close them.
R6 of the Counterpart Toolkit says it for SQL columns, Live / Snapshot / Cache mandatory. Any column derivable from other data must declare its category in the commit that creates it. If it's a Cache, the refresher mechanism (GENERATED ALWAYS AS
, SQL trigger, materialized view with planned REFRESH) ships in the same commit. No category declared, no commit.
backlog.md
is exactly the same logical object. Its value is derivable from state.json
plus a few editorial constants. sync-backlog.ts
is its applicative trigger. Without a call, the Cache drifts.
R2, Filesystem over summary, codifies the gesture since May 15. Before any status report, four shell commands, in this order. The markdown comes last, and it comes as draft thinking, never as a source.
git log --since='7d' --oneline
git status --porcelain
ls docs/adr/ | wc -l
cat scripts/devto/state.json | jq 'to_entries|map(select(.value.published))|length'
The result reads in three seconds. If something surprises me, a commit I had forgotten or one more ADR than memory expected, I dig there, not in backlog.md
. When I do read the markdown, I read it with the implicit question "who updated it, when", and if the answer doesn't come out of git log
in fifteen seconds, I treat it as rotten Cache.
A summary that doesn't say when it was produced, and by what mechanism, says nothing. Either you declare its refresher in the commit that creates it, be it a script, a trigger, a cron, and it lives as a managed Cache, or you stop treating it as a source and it goes back to being a draft. R6 says the rule for the database. R2 says the same rule for the writings you address to yourself. An agent that opens backlog.md
before git log
is not a bad agent, it's an agent that faithfully executes a human gesture that should have been forbidden upstream. The morning of May 21, it wasn't the agent that lied to me, it was my own typist who, the night before, hadn't closed the note.
Counterpart Toolkit v0.7, rule R2 — Filesystem over summary. Extracted from R1 in v0.4.1, promoted in its own right. Current version of the toolkit lives in CC-BY-4.0 on github.com/michelfaure/doctrine-counterpart.