jeffryandClaude Opus 5
6dcc06ab1c
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>
2.3 KiB
Publication
What a repository has handed over for others to depend on lives in
.loom/published/.
Publishing is a change of kind, not a change of status. An unpublished document is an implementation detail you may rename at will. A published one is a contract.
So publication is an act somebody performs — a file moves in — and the move is a diff that shows up in review. A flag in frontmatter is a line nobody notices; this is the moment a thing becomes somebody else's problem, and it 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 thinking some other way internally, that is its own business: a consumer cannot tell whether it did, and must not need to.
What is not exported is not hidden. The rest of the repository is there to read. It is simply not what you depend on.
There is no directory for what is unpublished
Everything else is simply elsewhere in the repository. Naming the complement
invents a category — and a directory called internal/ would look like a
security boundary and not be one.