01
Why an estate keeps two records, not one
You should be able to: State the difference between a claim about the future and a claim about the past, and why each needs its own shape.
A statement about the future is provisional by nature: it is true only until circumstances or priorities change, and an intention nobody acts on should quietly stop being asserted. A statement about the past is the opposite: once a thing has happened, the record of it must not move, or the history is worthless.
So the estate does not keep one "items" list with a status column. It keeps two formats with opposite guarantees. The future tense decays on purpose — an unattended intention ages out rather than standing as a broken promise. The past tense is sealed on purpose — a shipped entry is fixed the moment it is written.
The test of whether you have understood this: a roadmap item and a shipped entry should be impossible to confuse even with the labels removed, because one is allowed to disappear and the other is not allowed to change.
Source: FlashyOS — the protocol register (backlog/1, shipped/1)
02
The future tense: backlog/1
You should be able to: Describe how an intention is filed, why it decays, and who may promote it.
backlog/1 is one item per intention, federated per repository — each part of the estate keeps its own future tense rather than a central to-do list nobody trusts. An item carries what is intended and when it was last touched, and it decays: left unattended, it ages out rather than lingering as a commitment that was never real.
An item is filed private, and only a named human may promote it to something the world can read. That rule exists because the alternative — a fully public roadmap that never distributes anything — teaches every reader that the format is decorative. Distribution is a human decision, made by someone who can be asked why.
And a backlog item is closed by the machine that filed it, never by a person ticking it off — because the thing that knows an intention is finished is the process that was pursuing it, not a human tidying a list.
Source: FlashyOS — @flashyos/backlog
03
The past tense: shipped/1
You should be able to: Explain sealing, the union rule, and why a classification is final.
shipped/1 is one sealed entry per thing that shipped. Sealing means the entry is hashed through the same canonicalisation the estate uses for its settlements and receipts, so a stranger can verify offline that the entry has not changed since it was written. A sealed entry never decays: the past does not age out.
Emitting the log is a union, never a replacement. An id already in the fragment keeps its existing sealed entry; only genuinely new ids are added. This is what stops a re-run from silently rewriting history — the one thing a track record must never do.
When a commit's subject cannot say what kind of change it was, you say it out of band — a Kind: docs trailer, or a recorded classification — never by widening the vocabulary to guess a noun. And a sealed entry's classification is final: re-deriving the whole log from scratch is destructive, and once took a real log from 293 entries to 90. You append a correction; you do not re-cut the past.
Source: FlashyOS — @flashyos/shiplog
04
Why making them symmetric would break one
You should be able to: Say what breaks if the future tense is sealed or the past tense is allowed to decay.
The tempting simplification is to make the two formats one — same fields, same lifecycle, a status flag to tell them apart. It breaks both directions. Seal the future tense and an intention can no longer decay or be revised, so your roadmap becomes a wall of stale promises you cannot take back. Let the past tense decay and your track record quietly forgets things that happened, which is the exact failure a sealed log exists to prevent.
So the asymmetry is the design, not an accident waiting to be tidied. A correction to the future is a revision with a reason; a correction to the past is a new entry that supersedes, leaving the original in place. They are shaped by their tense, and the shapes are opposite because the tenses are.
The practical rule: before you reach for one format for both, ask which guarantee the claim needs — permission to disappear, or a promise never to change. You cannot have both in one record, and pretending you can is how a record starts lying.
Source: FlashyOS — the two tenses
05
Publishing versus holding
You should be able to: Distinguish a repository publishing its log from an individual entry being held, and why holding is not remediation.
A repository publishes its shipped log; an individual entry can still be held back. A held entry maps a specific commit to the reason it stays private — a small, auditable list, not a blanket switch. Holding lets an organization publish its record honestly while keeping the few entries it genuinely cannot show.
The sharp edge to learn here: holding is not remediation. Marking an entry private does not undo what is in the commit history — if a secret was committed, the commit message is still there, and only rotating the secret fixes it. Holding controls what the published log shows; it does nothing to what git already keeps.
So a held entry is an honest "we are not showing this, and here is the reason," never a way to pretend something did not happen. The record stays trustworthy precisely because it says when it is withholding, rather than silently dropping the row.
Source: FlashyOS — holding an entry (.shiplog/held.json)
