jeffryandClaude Opus 5
ffa56daa41
publication.md gains the procedure, with "fetch it, from somewhere that is not your machine and not your account" as its own step. Steps 1-3 are things you do; step 4 is a fact about the world you find out, which is why it is the one that gets skipped. Declined a separate procedural document: publishing.md beside publication.md is two files one letter apart, and the gap filed was that this document was underspecified. starting.md still described the worked example as private and refused to link it. It went public four days ago. The first page a newcomer reads was demonstrating its own lesson instead of teaching it. Entries 82-83. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.0 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.
Doing it
- Decide it is a contract and not a detail. This is the whole decision and the rest is mechanics.
- Move the file into
.loom/published/. One commit, so the diff carries it. - Say who the readers are — if it is not obvious from where it landed.
- Fetch it. From somewhere that is not your machine and not your account.
- Record the decision, if you keep a log.
Step 4 is the one that gets skipped and the only one that can fail. Steps 1 to 3 are things you do; step 4 is a fact about the world that you find out.
Then say what it depends on. A published document that quietly requires a private one has moved the problem rather than solved it.
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.