publication requires a reader; recording-decisions allows compaction
Both from gap files loom-cli filed as the first real adopter of externals. publication.md: "publishing is not an act you can complete alone" existed only in a sibling document as an aside about a tool. It is a property of the act and now says so, along with the fact that publication has a visibility — which externals' confidentiality rule depends on entirely and this document never mentioned. recording-decisions.md: "never revised" and "must be readable" conflict far enough out. Adopts loom-cli's rule verbatim in substance — drop what the artifact could recover, never drop a decline, a measurement, a belief shown wrong, or a supersession — because compaction is safe in exactly the cases where the entry was redundant and unsafe in exactly the cases the log exists for. Entries 79-81. annotating's gaps are left standing on purpose; it is the most depended-on document and its revision is Jeff's call. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -15,6 +15,28 @@ should be unmissable.*
|
||||
**`ls .loom/published/` is *what have we committed to?*** — and it is the question
|
||||
to ask before changing anything.
|
||||
|
||||
## Publishing is not an act you can complete alone
|
||||
|
||||
**A file in `.loom/published/` that its intended readers cannot fetch is not
|
||||
published.** *The move is the act, but the act is not finished until somebody who
|
||||
is not you can perform the read.*
|
||||
|
||||
> **The failure is invisible from the inside.** *Every check available to the
|
||||
> publisher passes — the file is there, the commit landed, the path is right.*
|
||||
> **Only a reader can detect it, and a reader who cannot fetch it does not know
|
||||
> the document exists to ask about.**
|
||||
|
||||
*The commonest form is a document that answers "why can you not see this?" and is
|
||||
published **inside** the thing that cannot be seen.*
|
||||
|
||||
**So publication has a visibility, and it is a property of the act rather than of
|
||||
the file.** *"Others" is not "everyone".* **Naming who the readers are is part of
|
||||
publishing**, because a repository that depends on this one has to know whether it
|
||||
is inside that set — *and because a reader who copies a document out inherits the
|
||||
copy without inheriting the visibility it was published under.*
|
||||
|
||||
**The test is a fetch you did not perform.**
|
||||
|
||||
## What is published is a document
|
||||
|
||||
**Prose, in whatever form its readers need.** *If a repository organises its
|
||||
|
||||
@@ -24,6 +24,29 @@ reads.*
|
||||
you already rejected — because the rejection lived somewhere that did not
|
||||
survive.*
|
||||
|
||||
## Compaction, and the entries it may never touch
|
||||
|
||||
**"Never revised" and "somebody must be able to read it" both hold, and far
|
||||
enough out they conflict** — *a log nobody can get through has stopped being a
|
||||
record.*
|
||||
|
||||
**Compaction is allowed. Dropping an entry is not the same as revising one**, and
|
||||
the uncompacted log is in git history, which is where a reader who needs it goes.
|
||||
|
||||
> **An entry may be dropped when a competent reader could recover it by reading
|
||||
> the artifact.**
|
||||
>
|
||||
> **An entry may never be dropped when it records a decline, a measurement, a
|
||||
> belief that was shown wrong, or one entry superseding another.**
|
||||
|
||||
*Which means **compaction is safe in exactly the cases where the entry was
|
||||
redundant with the artifact, and unsafe in exactly the cases the log exists
|
||||
for.*** **The four protected kinds are the ones with no other home:** *the code
|
||||
shows what was built and can never show what was refused, what was measured, what
|
||||
turned out false, or that somebody changed their mind.*
|
||||
|
||||
**A compaction is itself a decision, and gets an entry.**
|
||||
|
||||
## Where it lives
|
||||
|
||||
`.loom/event-log.md`. **A stream, so a file.**
|
||||
|
||||
Reference in New Issue
Block a user